How I Manage Python Environments in Codex with AGENTS.md
Source: http://x.com/i/article/2039698724667129857
You’ve might have seen your coding agent hit a kind of cold start: spending time figuring out which venv to use, which version is available, or even which package manager they should reach for.
I minimise this by making the workflow explicit with a
AGENTS.md file.
`AGENTS.md` is like a cheat sheet for agents like Codex: a quick guide to how to navigate a project, which rules to follow, and how to handle common tasks. Instead of spending time guessing, Codex starts with the right context.
One useful pattern is keeping a global `AGENTS.md` in your home directory, so Codex has clear defaults before it even enters a repo. Then project-level AGENTS.md files can override that guidance when needed.
When I use Python, I like using uv with both a project-local .venv and a shared global environment. It gives a clean split. Projects stay reproducible, with pinned dependencies and a consistent Python version. Everything else stays fast and lightweight.
If a project has a `pyproject.toml` or `requirements.txt`, Codex creates and uses a local .venv with Python 3.12. That keeps project work isolated and predictable.
For quick non-coding tasks or ad hoc scripts, spinning up a dedicated environment is often unnecessary. In those cases, Codex falls back to a minimal shared global environment instead.
Everything goes through uv. The agent does not spend time or tokens trying to infer setup. It follows a fixed path and moves straight to the work.
This is one use case for having a global `AGENTS.md`. What's in yours?
Learn more about AGENTS.md
here.
Here is my global AGENTS.md in full.
## Python Environment and Dependency Management
All Python work follows a deterministic setup to minimize environment drift and dependency conflicts.
### Tooling
Use `uv` for all environment and dependency operations. Do not use `pip`, `poetry`, or `conda` directly.
### Python Version
Default to **Python 3.12** for all new projects and environments unless explicitly specified otherwise.
### Project Root (Default)
- Default project root is the current working directory (`cwd`).
- Monorepo rule: if the task clearly targets a subdirectory that contains dependency files, treat that subdirectory as the project root for env setup. Otherwise use the repo root.
### Dependency Declaration (Explicit)
A project is considered to declare dependencies if **any** of these exist at the project root:
- `pyproject.toml`
- `requirements.txt`
- `requirements-dev.txt`
- `requirements.lock` Other files (e.g., `requirements.in`, `Pipfile`, `setup.cfg`) are ignored unless the user explicitly asks to use them.
### Environment Selection Rules (Defaults)
1. Prefer a project-local virtual environment in `<project-root>/.venv`.
2. Create one only if the project declares dependencies.
3. If `.venv` already exists in the project root, reuse it.
4. If no dependency files exist, use the shared global environment.
### Decision Tree (Default Flow)
1) Does `<project-root>/pyproject.toml` exist?
- Yes ->
- `uv venv .venv --python 3.12`
- `uv sync`
- `source .venv/bin/activate`
- If no lockfile exists, allow `uv sync` to create it.
2) Else, does `<project-root>/requirements.txt` exist?
- Yes ->
- `uv venv .venv --python 3.12`
- `uv pip install -r requirements.txt`
- If running tests/linters and `requirements-dev.txt` exists, also:
- `uv pip install -r requirements-dev.txt`
- `source .venv/bin/activate` 3) Else, does `<project-root>/requirements-dev.txt` exist (and no `requirements.txt`)?
- Yes ->
- `uv venv .venv --python 3.12`
- `uv pip install -r requirements-dev.txt`
- `source .venv/bin/activate` 4) Else ->
- `source ~/personal/bin/activate`
- Use `uv pip` only if new deps are strictly required.
### Activation Requirement
Always activate the environment **before**:
- Running scripts
- Installing dependencies
- Executing tests
- Invoking Python CLIs
Activation command:
bash
source .venv/bin/activate
Note: `uv sync` and `uv run` can operate without manual activation, but explicit activation is required for direct script execution.
### Global Environment Fallback
If **no dependency files exist**, use the shared global environment:
bash
source ~/personal/bin/activate
When operating in the global environment:
- Use `uv pip` exclusively.
- Never use `pip` directly.
- Avoid adding new dependencies unless strictly required.
### Non-Negotiables
- Do not mix environments within a session.
- Do not install dependencies implicitly.
- Do not assume system Python.
- Do not create ad-hoc virtual environments outside the project directory.
- Always use Python 3.12 for new projects unless explicitly specified otherwise.
- Use `uv sync` for projects with `pyproject.toml` and dependency declarations.