# How ai-agent-book Manages Dependencies with uv and pyproject.toml Optional-Dependencies

> Discover how ai-agent-book uses pyproject.toml optional-dependencies and uv for efficient dependency management. Achieve lightweight installs and reproducible environments.

- Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book)
- Tags: how-to-guide
- Published: 2026-08-23

---

**The ai-agent-book project leverages PEP 621-style [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml) to declare modular optional-dependency groups (extras) that the uv package manager resolves into platform-specific lockfiles, enabling lightweight core installations and reproducible chapter-level environments.**

The `bojieli/ai-agent-book` repository demonstrates modern Python dependency management by combining standardized project metadata with high-performance tooling. Instead of maintaining multiple [`requirements.txt`](https://github.com/bojieli/ai-agent-book/blob/main/requirements.txt) files, the project centralizes its dependency graph in a single [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml) while using **uv** to handle complex resolution scenarios. This architecture allows readers to install only the libraries required for specific chapters or experiments.

## Core and Optional Dependency Structure

The project's [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml) defines runtime requirements using PEP 621 fields, separating minimal core dependencies from feature-specific extras.

### Core Requirements

The `[project] dependencies` array lists packages essential for all functionality. According to lines 19-30 of [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml), these include `openai`, `pydantic`, `python-dotenv`, and `requests`. These dependencies install by default with any package consumption method.

### Optional Dependency Groups

Under `[project.optional-dependencies]`, the project organizes related libraries into semantic groups:

- **viz**: Visualization libraries including `matplotlib`, `pandas`, and `seaborn` (lines 60-70)
- **docs**: Document processing tools such as `pypdf`, `PyPDF2`, and `python-docx` (lines 72-84)
- **media**: Image and video handling via `pillow` and `opencv-python` (lines 87-91)
- **web**: HTTP operations with `aiohttp`, `beautifulsoup4`, and `playwright` (lines 94-102)
- **browser**: Browser automation agents that depend on the `web` extra (lines 105-110)
- **serve**: FastAPI service dependencies (lines 112-117)

### Composable Chapter Aggregates

The project creates higher-level aggregates that reference multiple base extras for specific chapters. For example, `ch1` requires only visualization and document handling, while `ch2` pulls in visualization, documents, web, serving, and ML providers:

```toml
[project.optional-dependencies]
ch1 = ["agentbook[viz,docs]"]
ch2 = ["agentbook[viz,docs,web,serve,providers,tokens,torch]"]

```

This composability prevents dependency bloat while maintaining explicit chapter-level contracts.

## How uv Resolves and Locks Dependencies

The `uv` tool reads configuration from the `[tool.uv]` section to generate deterministic lockfiles that respect platform constraints and package incompatibilities.

### Handling Package Conflicts

The repository explicitly declares that the `unsloth` extra (for Linux GPU fine-tuning) cannot coexist with the `vllm` extra (for Linux GPU inference) because they pin incompatible `transformers` versions. This conflict is defined under `[tool.uv] conflicts` (lines 38-46), preventing uv from creating invalid environments.

### Platform-Specific Environments

Uv generates separate lockfiles for macOS (ARM), Linux (x86_64), and Windows (lines 48-54), ensuring each platform receives a compatible dependency resolution without manual specification.

## Installation Workflows and Commands

Users interact with the dependency system through uv commands or standard pip syntax.

To install only the dependencies needed for Chapter 1:

```bash
uv sync --extra ch1

```

For the full GPU fine-tuning stack on Linux:

```bash
uv sync --extra unsloth

```

Non-uv users can achieve similar results using pip with extras notation:

```bash
pip install -e ".[ch1]"

```

However, pip performs fresh resolution rather than utilizing uv's pre-generated lockfile.

## Summary

- The project centralizes dependency definitions in [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml) using PEP 621 optional-dependencies
- **Extras** like `viz`, `docs`, and `web` group related libraries while **chapter aggregates** (e.g., `ch1`, `ch2`) compose these for specific use cases
- **uv** generates platform-specific lockfiles and enforces conflict rules (e.g., `unsloth` vs `vllm` incompatibility)
- Installation granularity ranges from minimal core packages to full chapter environments using `uv sync --extra <name>`

## Frequently Asked Questions

### What is the difference between core and optional dependencies in ai-agent-book?

Core dependencies listed under `[project] dependencies` in [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml) install with every package usage and include fundamental libraries like `openai` and `pydantic`. Optional dependencies are organized into extras groups under `[project.optional-dependencies]` that users must explicitly request via `uv sync --extra <group>` or `pip install -e ".[<group>]"`, keeping the base installation lightweight.

### Why does uv prevent installing unsloth and vllm extras together?

According to the `[tool.uv] conflicts` section in [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml) (lines 38-46), the `unsloth` extra (Linux GPU fine-tuning) and `vllm` extra (Linux GPU inference) declare conflicting version pins for the `transformers` library. Uv enforces this mutual exclusivity during resolution to prevent runtime version incompatibilities.

### How do I install dependencies for a specific chapter without uv?

Users can install chapter-specific dependencies using standard pip with extras notation: `pip install -e ".[ch1]"` or `pip install -e ".[ch2]"`. While this installs the same package sets defined in [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml), pip resolves dependencies dynamically rather than using uv's pre-generated lockfile, potentially yielding different versions.

### Where are the dependency definitions stored in the repository?

All dependency specifications reside in the root [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml) file. Core requirements appear under `[project] dependencies`, optional groups under `[project.optional-dependencies]`, and uv-specific configuration (conflicts and environment targets) under `[tool.uv]`. Some chapters may include supplementary [`requirements.txt`](https://github.com/bojieli/ai-agent-book/blob/main/requirements.txt) files for experiments requiring isolated environments.