adk-setup

ADK Python Development Setup

Set up a working adk-python checkout: a uv-managed virtual environment with every dependency extra, pre-commit hooks, and a green unit-test run.

Prerequisites

1. Python. ADK supports 3.11 through 3.15 (requires-python = ">=3.11" in pyproject.toml). These steps use 3.11, the version the repo's own tooling defaults to.

   python3 --version
   

2. uv. Dependencies are declared in pyproject.toml. The uv sync step below creates a local uv.lock, which this repository ignores. Run that step before tox, whose lock runner requires the file.

   uv --version
   

   Install it if missing:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

Setup

Run these from the repository root.

1. Create and activate the virtual environment:

   uv venv --python "python3.11" ".venv"
   source .venv/bin/activate
   

2. Install every dependency extra:

   uv sync --all-extras
   

   --all-extras is what pulls in the test and dev extras. Syncing only the default dependencies leaves pytest and the linters uninstalled.

3. Install pre-commit and tox as standalone tools:

   uv tool install pre-commit
   uv tool install tox --with tox-uv
   

   Both are also in the dev extra; installing them as uv tools puts them on PATH so the git hook and multi-version test runs work without an activated venv.

4. Install addlicense (optional, requires Go):

   go install github.com/google/addlicense@latest
   

   Without it the pre-commit hook prints Warning: addlicense not installed, skipping and passes, so a missing Go toolchain does not block setup — CI catches missing license headers instead.

5. Install the git hooks:

   pre-commit install
   

   On each commit the hooks auto-format with isort, pyink, and mdformat, then run ruff, addlicense, codespell, and the repo's own compliance checks.

6. Verify the environment:

   pytest tests/unittests -n auto
   

   A green run here is the success criterion for setup. -n auto needs pytest-xdist, which arrives with the test extra in step 2.

Key commands

Task	Command
Run unit tests	pytest tests/unittests
Run unit tests in parallel	pytest tests/unittests -n auto
Run one test file	pytest tests/unittests/agents/test_base_agent.py
Run tests on every supported Python	tox (uv downloads any missing interpreters)
Format and lint everything	pre-commit run --all-files
Launch the web UI	adk web {agents_dir}
Run an agent from the CLI	adk run {agent_dir}
Build the wheel	uv build