This guide explains how to install Agent-Lightning. You can install it from PyPI (the Python Package Index) for general use or directly from the source code if you plan to contribute or need fine-grained control over dependencies.
!!! info "Platform and Hardware Requirements" Agent-Lightning is officially supported on Linux distributions (Ubuntu 22.04 or later is recommended). At the moment macOS and Windows (outside of WSL2) are not supported.
The Python runtime must be **Python 3.10 or newer**. We recommend using the latest patch release of Python 3.10, 3.11, or 3.12 to pick up performance and security updates.
A **GPU is optional**—you only need CUDA-capable hardware if you plan to fine-tune model weights or run GPU-accelerated workloads. CPU-only environments are fully supported for evaluation and inference.
The easiest way to get started is by installing Agent-Lightning directly from PyPI. This ensures you get the latest stable release of the package, tested for compatibility and reliability.
Run the following command in your terminal:
pip install --upgrade agentlightningThis installs or upgrades Agent-Lightning to the newest stable version.
!!! tip
If you intend to use **Agent-Lightning** with [**VERL**](../algorithm-zoo/verl.md) or run any of its **example scripts**, you’ll need to install some additional dependencies.
See the sections on [Algorithm-specific installation](#algorithm-specific-installation) and [Example-specific installation](#example-specific-installation) for details.
Agent-Lightning also publishes nightly builds, which contain the latest experimental features and improvements from the main branch. These are available via Test PyPI.
pip install --upgrade --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ --pre agentlightning!!! warning The nightly builds are cutting-edge but may include unstable or untested changes. Use them at your own risk, especially in production environments.
Agent-Lightning supports multiple learning algorithms. Some of them like APO or VERL require extra dependencies. You can install them automatically using optional extras or manually if you prefer finer control.
APO is an algorithm module that depends on libraries such as POML. You can install Agent-Lightning with APO support by running:
pip install agentlightning[apo]!!! warning APO also depends on the OpenAI Python SDK, version 2.0 or newer. Ensure your SDK version is up to date to avoid compatibility issues.
VERL integrates with libraries like PyTorch, vLLM, and VERL framework. Although you can install all dependencies automatically, we recommend doing it manually to avoid version conflicts.
pip install agentlightning[verl]!!! tip "Recommended Manual Setup (More Stable)" Automated installation may cause issues if you don’t have a compatible PyTorch or CUDA version preinstalled. For a more stable setup, install dependencies step-by-step:
```bash
pip install torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128
pip install flash-attn --no-build-isolation
pip install vllm==0.10.2
pip install verl==0.5.0
```
This approach ensures compatibility with CUDA 12.8 and minimizes dependency conflicts.
Each example in the examples/ directory may have its own additional dependencies.
Please refer to the README file of each example for detailed setup instructions:
[See Example READMEs]({{ src("examples") }}).
If you plan to contribute to Agent-Lightning or prefer to work with the latest development code, install it directly from the source repository.
- You want to modify or contribute to the project.
- You prefer an isolated development environment.
- You want to test unreleased features or fix bugs locally.
Starting with version 0.2, Agent-Lightning uses uv as its default dependency manager.
uv is a fast and safe alternative to pip that:
- Installs packages in seconds (instead of minutes),
- Prevents dependency conflicts,
- Supports grouped dependencies for optional features.
Before proceeding, make sure uv is installed.
git clone https://github.com/microsoft/agent-lightning
cd agent-lightning
uv sync --group devThis command sets up a clean development environment with only the essential dependencies.
uv sync can also handle algorithm-specific and example-specific dependencies in one step.
For a CPU-only machine:
uv sync --frozen \
--extra apo \
--extra verl \
--group dev \
--group torch-cpu \
--group torch-stable \
--group trl \
--group agents \
--no-default-groupsFor a GPU-equipped machine that is CUDA 12.8 compatible:
uv sync --frozen \
--extra apo \
--extra verl \
--group dev \
--group torch-gpu-stable \
--group trl \
--group agents \
--no-default-groupsRead more about Agent-lightning managed dependency groups [here]({{ src("pyproject.toml") }}).
The Agent-Lightning dashboard is built using Vite. To build the dashboard, run the following command:
cd dashboard
npm ci
npm run buildSome HTML and JavaScript assets will be generated in the agentlightning/dashboard directory.
After syncing dependencies, uv automatically creates a virtual environment inside the .venv/ directory.
You can use it in two ways:
# Option 1: Prefix commands with uv run
uv run python your_script.py
# Option 2: Activate the virtual environment
source .venv/bin/activate
python your_script.py!!! warning "Before Contributing"
Agent-Lightning enforces code style and linting rules via **pre-commit hooks**.
Installing them early prevents many avoidable formatting issues.
```bash
uv run pre-commit install
uv run pre-commit run --all-files --show-diff-on-failure --color=always
```