How to set up a fast, reproducible Python project with uv

When you point an AI coding agent like Claude Code or Codex at a Python project, half the friction has nothing to do with the model. It comes from the environment: missing packages, the wrong Python version, a virtualenv the agent forgot to activate, or a teammate who "works on my machine." The fix is a project that is reproducible by default, and the fastest way to get one today is uv, the Rust-based Python toolchain from Astral.

uv replaces pip, venv, pip-tools, and pyenv with a single fast command, and it writes a lockfile so the exact same dependency tree installs everywhere. This guide gets you from nothing to a locked, runnable project in a few minutes.

Why the environment matters to an agent

An AI agent runs commands in your shell and reads the errors that come back. If your project has no declared dependencies and no pinned Python version, the agent has to guess — and a wrong guess sends it down a rabbit hole of installing packages globally or editing the wrong interpreter. A project with a pyproject.toml and a uv.lock gives the agent a single source of truth: it can run uv sync, get the right packages, and move on. You spend your review time on logic, not on environment archaeology.

Install uv

On macOS or Linux:

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

On Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

uv is a single self-contained binary, so there is nothing else to configure.

Start a project in one command

uv init weather-cli
cd weather-cli

That scaffolds a working project: a pyproject.toml for metadata and dependencies, a .python-version file, a starter main.py, a README.md, and a .gitignore. You do not create or activate a virtualenv by hand — uv manages a .venv for you the moment you need it.

Add dependencies (and why the lockfile matters)

uv add requests

This does three things at once: records requests in pyproject.toml, resolves the full dependency tree, and writes uv.lock with exact, cross-platform pinned versions. You can pin at add time too:

uv add 'requests==2.31.0'

Commit uv.lock to Git. It is the difference between "install the latest requests" (which drifts over time) and "install the exact tree we tested." When your agent — or your CI, or a new teammate — runs uv sync, they get a byte-for-byte identical environment.

Run code without activating anything

uv run main.py

uv run ensures the environment is in sync, then executes inside it — no source .venv/bin/activate dance. This matters for agents especially: each tool call is often a fresh shell, so "activate then run" frequently breaks, while a single uv run always works. You can wrap any command:

uv run -- pytest -q
uv run -- flask run -p 3000

Pin a Python version so the agent and CI agree

uv python pin 3.12

This writes the version into .python-version, and uv will download and use that interpreter automatically — no system Python required. Now the version you develop against is the version your agent, your teammates, and your CI all use.

A short worked example

Say you ask an agent to "add a command that fetches today's weather." With uv in place, the whole loop is clean:

uv init weather-cli && cd weather-cli
uv add requests
uv python pin 3.12
# the agent edits main.py to call an API...
uv run main.py

The agent never has to reason about which interpreter is active or whether requests is installed — those facts are declared in files it can read. If it introduces a new dependency, it runs uv add and the lockfile updates. If something breaks in CI, uv sync reproduces the exact environment locally so you can debug it.

Where uv is headed

uv and its sibling tools ruff (linter/formatter) and ty (type checker) are widely adopted — uv alone sees well over 100 million downloads a month. In March 2026, OpenAI agreed to acquire Astral, the company behind them, to fold the toolchain into its Codex platform, while committing to keep the MIT-licensed tools open source (OpenAI, Simon Willison). For now the practical takeaway is unchanged: uv is the fastest path to a Python project your AI agent can build on without guessing.

Quick reference

Task	Command
Create a project	uv init <name>
Add a dependency	uv add <package>
Pin Python	uv python pin 3.12
Run code	uv run <file or command>
Reproduce the env	uv sync
Update the lockfile	uv lock --upgrade-package <pkg>