python-env

Python Environment

Fast Python environment management with uv. Prefer the uv project workflow (uv add / uv sync / uv run) over the uv pip compatibility layer — it manages pyproject.toml + a lockfile for you and is reproducible.

Quick Commands

Task	Command
Start a project	uv init <name> (app) · uv init --package <name> (installable, src/ layout)
Add dependency	uv add httpx
Add dev dependency	uv add --dev pytest ruff
Remove dependency	uv remove httpx
Sync env from lockfile	uv sync
Run in project env	uv run pytest
Update lockfile	uv lock
Install a CLI tool	uv tool install ruff · one-shot: uvx ruff
Install a Python	uv python install 3.12

Start a Project

# Application (flat layout, no package build)
uv init myapp

# Installable package (src/ layout — separate tests/ that import by name)
uv init --package wordtools
# → src/wordtools/__init__.py, pyproject.toml with build-system

uv init creates pyproject.toml, pins a Python version, and prepares the project for uv add / uv sync. The --package (src) layout is preferred for anything with a test suite or that you intend to ship.

Manage Dependencies

# Add runtime deps (writes to [project.dependencies] + updates the lockfile)
uv add "httpx>=0.25" pydantic

# Add dev-only deps (writes to the dev dependency-group)
uv add --dev pytest ruff mypy

# Add with extras
uv add "fastapi[standard]"

# Remove
uv remove httpx

# Install everything from pyproject + uv.lock into .venv (reproducible)
uv sync

# Refresh the lockfile (e.g. after manual pyproject edits)
uv lock

uv creates and manages .venv automatically — you rarely activate it; just prefix commands with uv run.

Run Code

uv run python script.py     # run a script in the project env
uv run pytest               # run a tool from the dev group
uv run -- ruff check .      # `--` ends uv flag parsing

Never call bare python / pytest / ruff in a uv project — they may resolve to a different interpreter. Always uv run.

CLI Tools (global, not project deps)

uv tool install ruff        # persistent, isolated, on PATH
uv tool upgrade ruff
uvx ruff check .            # ephemeral one-shot run, nothing installed

Use uv tool / uvx for developer CLIs (ruff, pre-commit, httpie). Use uv add only for things your code imports.

Python Versions

uv python install 3.12      # download a managed interpreter
uv python list              # show available + installed
uv init --python 3.12 app   # pin a project to a version

3.13 is the current stable release (free-threading and JIT, both opt-in); 3.11+ is a sensible floor for new projects (TaskGroup, Self, faster interpreter).

Minimal pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "httpx>=0.25",
    "pydantic>=2.0",
]

# Dev deps live here; `uv add --dev <pkg>` manages this group.
[dependency-groups]
dev = [
    "pytest>=8.0",
    "ruff>=0.4",
    "mypy>=1.10",
]

Compatibility Layer (uv pip) — last resort

uv pip mirrors pip's interface for environments uv doesn't manage (a hand-made venv, a legacy requirements.txt, CI that isn't uv-native). It does not update pyproject.toml or the lockfile — prefer uv add / uv sync whenever you control the project.

uv venv                              # bare venv (no project)
uv pip install -r requirements.txt   # legacy requirements file
uv pip install -e .                  # editable install into an unmanaged venv
uv pip compile requirements.in -o requirements.txt   # pin a requirements.txt

Troubleshooting

Issue	Solution
"No Python found"	uv python install 3.12
Pin project Python	uv init --python 3.12 or edit requires-python
Lock/resolve conflict	uv lock --resolution=lowest-direct to probe, then loosen bounds
Stale env after pull	uv sync
Cache issues	uv cache clean

When to Use

• Always use uv over pip — 10-100x faster
• uv add / uv remove / uv sync for project dependencies (not uv pip install)
• uv run to execute anything inside the project env
• uv tool install / uvx for standalone developer CLIs
• uv pip only for environments uv doesn't manage

Additional Resources

For detailed patterns, load:

• ./references/pyproject-patterns.md - Full pyproject.toml examples, tool configs
• ./references/dependency-management.md - Lock files, workspaces, private packages
• ./references/publishing.md - PyPI publishing, versioning, CI/CD

---

See Also

This is a foundation skill with no prerequisites.

Build on this skill:

• python-typing-ops - Type hints for projects
• python-pytest-ops - Testing infrastructure
• python-fastapi-ops - Web API development