How to Install Chapter-Specific Dependencies using uv sync --locked --extra chN

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. 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. 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):

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:

uv sync --locked --extra ch2 --extra vllm

Other common combinations include development tools (dev) and GPU-optimized fine-tuning libraries (unsloth):

# 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:

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:

uv run python chapter1/context/main.py

Alternatively, after installation via either uv or pip, you can run scripts directly with the activated environment:

python chapter1/context/main.py

Per-chapter usage examples and specific flags are documented in the individual chapterX/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 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 (where X is the chapter number) and the main installation guide in docs/en/README.md. The [project.optional-dependencies] section in pyproject.toml defines the actual package sets referenced by the --extra flags.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}