AI projects have heavy, fast-moving dependency trees: model SDKs, PydanticAI, vector database clients, tokenizers, and sometimes CUDA-specific wheels. Slow installs and environments that differ between machines waste hours.
uv, built by Astral in Rust, has become the default choice for many Python teams because it resolves and installs packages far faster than pip and gives you a lockfile out of the box.
1. Start a Project
# Install uv (macOS / Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Create a project with a pinned Python version
uv init support-agent
cd support-agent
uv python pin 3.12
# Add dependencies
uv add pydantic-ai httpx
uv add --dev pytest ruff
uv add updates pyproject.toml, resolves versions, writes uv.lock, and syncs the .venv in one step.
2. Run Without Activating Anything
uv run python -m support_agent
uv run pytest -q
uv run makes sure the environment matches the lockfile before it executes the command, so it cannot drift silently.
3. Reproducible Installs in CI
uv sync --locked
With --locked, the command fails if pyproject.toml and uv.lock disagree, catching dependency changes that were never committed.
4. Small, Cache-Friendly Docker Images
FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --locked --no-dev --no-install-project
COPY . .
RUN uv sync --locked --no-dev
CMD ["uv", "run", "python", "-m", "support_agent"]
Copying the dependency files first lets Docker cache the dependency layer, so code-only changes rebuild in seconds.
5. Quick Migration Checklist
- Run
uv initin the existing repository, or keep your currentpyproject.toml. - Import existing pins with
uv add -r requirements.txt. - Commit
pyproject.toml,uv.lockand.python-version. - Replace
pip installsteps in CI withuv sync --locked. - Replace
python script.pywithuv run script.pyin docs and Makefiles.
Get Weekly AI Architect Cost & Strategy Updates
Join 14,000+ developers receiving weekly, data-driven cost-reduction blueprints and production-ready agent guidelines.
