Skip to content

How to Configure Codex to Use uv

A repository-level AGENTS.md keeps Codex on the same uv 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
  • 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:

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

uv sync --locked creates or updates the project’s virtual environmentAn isolated folder where Python installs packages for one project, keeping them separate from other projects and your system Python. Learn more โ†’ 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:

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 development dependencyA package needed during development (testing, linting, formatting) that is not shipped to users of your project. Installed with the --dev flag. , 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:

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:

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.

Last updated on