# How to Install Chapter-Specific Dependencies using uv sync --locked --extra chN > Install chapter specific dependencies for the AI Agent Book using uv sync --locked --extra chN. Ensure precise version control for each chapter by following this simple command. - Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book) - Tags: how-to-guide - Published: 2026-08-23 --- **Run `uv sync --locked --extra chN` (where N is the chapter number) to install the exact dependency versions specified in the repository's lockfile for that specific chapter of the AI Agent Book.** The **bojieli/ai-agent-book** repository uses **uv**, a high-performance Python package manager, to handle its complex dependency graph across ten distinct chapters. Each chapter's requirements are isolated as optional dependency groups named `ch1` through `ch10` in [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml). Using `uv sync --locked --extra` ensures you install precisely the versions recorded in `uv.lock`, guaranteeing reproducible environments that match the authors' original experimentation setup. ## Understanding Chapter Extras in pyproject.toml The dependency groups are declared in the `[project.optional-dependencies]` section of **[pyproject.toml](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml)**. Each extra corresponds to a specific chapter's import requirements, allowing you to install only the packages needed for the code you intend to run. When you invoke `uv sync` with an `--extra` flag, uv reads the `uv.lock` file and materializes the exact pinned versions for that dependency subgraph. This avoids pulling in unnecessary packages from other chapters. ## Installing Dependencies for a Single Chapter To install the minimal dependencies required for Chapter 1 (CPU-friendly, no GPU stack): ```bash uv sync --locked --extra ch1 ``` The `--locked` flag is critical for reproducibility. It instructs uv to install from the lockfile without performing fresh version resolution, ensuring your environment matches the locked state. ## Combining Multiple Extras You can install multiple chapters or add optional runtime stacks by chaining `--extra` flags. For example, to install Chapter 2 alongside the `vllm` serving stack: ```bash uv sync --locked --extra ch2 --extra vllm ``` Other common combinations include development tools (`dev`) and GPU-optimized fine-tuning libraries (`unsloth`): ```bash # Chapter 5 with linting and testing tools uv sync --locked --extra ch5 --extra dev # Chapter 7 fine-tuning dependencies with Unsloth GPU support uv sync --locked --extra ch7 --extra unsloth ``` ## Fallback Installation with pip If uv is unavailable, you can achieve similar results using pip by installing the package in editable mode with the desired extras. Note that pip resolves dependencies freshly rather than using the lockfile: ```bash python -m pip install -e ".[ch2,vllm]" ``` This command installs both the Chapter 2 dependencies and the vllm stack, though without the version pinning guarantees provided by `uv.lock`. ## Running Experiments After Installation Once dependencies are synchronized, execute chapter scripts using `uv run` to ensure the correct virtual environment is activated automatically: ```bash uv run python chapter1/context/main.py ``` Alternatively, after installation via either uv or pip, you can run scripts directly with the activated environment: ```bash python chapter1/context/main.py ``` Per-chapter usage examples and specific flags are documented in the individual **[chapterX/README.en.md](https://github.com/bojieli/ai-agent-book/blob/main/chapter1/README.en.md)** files (replace *X* with your target chapter number). ## Summary - **Use `uv sync --locked --extra chN`** to install exact pinned versions for chapter N from the `uv.lock` file. - **Reference [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml)** to see available optional dependency groups (`ch1` through `ch10`, plus `vllm`, `unsloth`, `dev`). - **Combine extras** by repeating the `--extra` flag for multi-chapter workflows or optional runtime stacks. - **Prefer `--locked`** to guarantee reproducibility; omitting it allows uv to update the lockfile. - **Fallback to pip** with `pip install -e ".[extra1,extra2]"` if uv is not installed, though this re-resolves versions. ## Frequently Asked Questions ### What does the --locked flag do in uv sync? The `--locked` flag instructs uv to install dependencies using only the versions recorded in the existing `uv.lock` file without performing fresh version resolution. According to the bojieli/ai-agent-book source code, this guarantees that your environment matches the exact dependency graph used when the experiments were originally authored, ensuring full reproducibility. ### Can I install dependencies for multiple chapters at once? Yes. You can specify multiple extras in a single command by repeating the `--extra` flag. For example, `uv sync --locked --extra ch2 --extra ch3` installs the combined dependency sets for both Chapter 2 and Chapter 3, along with any shared dependencies resolved to compatible versions in the lockfile. ### How do I install chapter dependencies if I don't have uv installed? If uv is unavailable, install the package in editable mode using pip with the specific extras bracket notation: `python -m pip install -e ".[chN]"` (replace N with the chapter number). Keep in mind that pip performs fresh resolution rather than reading from `uv.lock`, so versions may differ from the locked state. ### Where are the chapter-specific installation instructions documented? Detailed usage examples and any chapter-specific flags or requirements are documented in the per-chapter README files located at [`chapterX/README.en.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapterX/README.en.md) (where X is the chapter number) and the main installation guide in **[docs/en/README.md](https://github.com/bojieli/ai-agent-book/blob/main/docs/en/README.md)**. The `[project.optional-dependencies]` section in [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml) defines the actual package sets referenced by the `--extra` flags.