# How to Configure Codex to Use uv


A repository-level `AGENTS.md` keeps [Codex](https://pydevtools.com/handbook/explanation/codex-complete-guide.md) on the same [uv](https://pydevtools.com/handbook/reference/uv.md) workflow as the project. Record the uv commands and repository checks once, then confirm that a new Codex session loads them before assigning code changes.

## Prerequisites

- Codex installed and authenticated
- [uv installed](https://pydevtools.com/handbook/how-to/how-to-install-uv.md)
- An existing uv project with `pyproject.toml` and `uv.lock` committed
- The repository's configured lint, test, format, and type-check commands

## Confirm the locked environment

Run the locked sync from the repository root before configuring the agent:

```bash
uv sync --locked
git diff --exit-code -- pyproject.toml uv.lock
```

`uv sync --locked` creates or updates the project's {{< term "virtual-environment" >}} without changing an outdated lockfile. The second command prints nothing when the project metadata and lockfile remain unchanged.

Resolve a stale lockfile or a failing baseline check before delegating project work.

## Record the uv workflow

Create `AGENTS.md` at the repository root:

```markdown {filename="AGENTS.md"}
# Python workflow

- This repository uses uv. Do not use pip or create another virtual environment.
- Read pyproject.toml before changing dependencies or tool settings.
- Add runtime dependencies with `uv add <package>`.
- Add development dependencies with `uv add --dev <package>`.
- Run Python commands and project tools with `uv run`.
- Sync the existing environment with `uv sync --locked`.
- Keep pyproject.toml and uv.lock in the same change when dependencies change.

## Verification

- Run `uv run ruff check .` after editing Python.
- Run `uv run ruff format --check .` after editing Python.
- Run `uv run pytest` before reporting completion.
- Report the exact command and error for any check that cannot run.
```

The `--dev` flag marks a tool as a {{< term "dev-dependency" "development dependency" >}}, keeping it out of production installs. `uv run` executes the command inside the project's virtual environment, ensuring all dependencies are installed first.

Replace the Ruff and pytest lines with the commands that already pass in the repository. Do not tell Codex to run a tool that the project has not configured.

Commit `AGENTS.md` so every session using the repository receives the same rules. Keep personal preferences in the global Codex instructions instead of mixing them into the shared file.

## Verify the loaded instructions

Start a new Codex session from the repository root after creating or changing `AGENTS.md`. Paste this read-only request:

```text
Summarize the repository's uv commands and checks from AGENTS.md. Do not edit
files or run project commands.
```

The response should name `uv add`, `uv add --dev`, `uv run`, `uv sync --locked`, and the repository's checks. If a rule is missing, inspect `AGENTS.md` and `AGENTS.override.md`. Then restart Codex from the repository root.

Codex reads instructions when a run starts. Editing `AGENTS.md` does not update an existing session's instruction chain.

## Verify the workflow during a code change

Give Codex a bounded task that requires one of the recorded commands. Review its command log and diff before accepting the result:

```text
Fix the failing parser test without changing the public API. Reproduce the
failure first, make the smallest code change, then run the repository checks
from AGENTS.md. Report each command and its result.
```

Confirm that dependency changes use `uv add` and tools use `uv run`. Keep `pyproject.toml` paired with `uv.lock`. Instructions guide Codex; CI or pre-commit should still enforce the checks independently.
