Coding Python Uv

uv - Python Package & Project Manager

All documentation files are flat, numbered markdown files. Use the Read tool to load referenced files identified as relevant for full details.

Command-to-Document Quick Reference

Document Index

Cross-Reference by Scenario

Key Environment Variables

Gotcha: a stray VIRTUAL_ENV hijacks tools

An ambient VIRTUAL_ENV (set by an IDE like PyCharm, or carried over from another project's shell) leaks into tools that otherwise manage their own environment - uv, pip-audit, tox, nox, and Makefile targets that fall back to python3 on PATH. The symptom is a tool running against the WRONG interpreter: ModuleNotFoundError inside an isolated venv, a flood of phantom type-check errors, or pip-audit failing on CVEs from an unrelated shared env.

Default: strip the ambient env for every local test/lint/build, do not wait for it to break. Prefix the invocation rather than relying on the inherited environment:

env -u VIRTUAL_ENV uv run pytest          # tests/lint/type-check: isolate to the project venv
env -u VIRTUAL_ENV uv run pyright
# for the bmk pipeline (Makefile targets), pin the project interpreter too:
env -u VIRTUAL_ENV BMK_PYTHON_CMD="$PWD/.venv/bin/python" \
  PIPAPI_PYTHON_LOCATION="$PWD/.venv/bin/python" make test

"Fresh" means the project's own venv, isolated - only RECREATE it (uv venv --clear .venv && uv sync) when a failure looks like genuine env corruption; recreating on every run is slow and rarely needed. Confirm which interpreter you got with uv run python -c "import sys; print(sys.executable)" (it should point at ./.venv) before trusting a "missing module" or phantom-type failure.

.venv/ is local - never commit it. uv's project venv is a per-machine artifact (absolute paths, platform binaries); ensure .venv/ is gitignored and untrack it if it slipped in. Mechanics (and the full artifact list) live in bitranox:compuse-git "Don't track local build artifacts".

Gotcha: on Windows, spawning a uv-installed tool by bare name needs shutil.which first

uv installs a tool (ruff, pytest, pyright) into its own venv bin/Scripts dir, NOT on the caller's PATH. When your Python spawns it via subprocess by bare name, Windows breaks where POSIX does not: subprocess.Popen([...], env=E) on POSIX resolves a bare-name argv[0] with E["PATH"] (execvpe), but on Windows CreateProcess resolves the executable against the CALLING process's %PATH% and IGNORES the env dict you pass to the child - so pointing the child's PATH at the tool dir does nothing and you get FileNotFoundError [WinError 2].

# resolve argv[0] to an absolute path FIRST (honours PATHEXT, so "ruff" -> "ruff.exe"):
resolved = shutil.which(argv[0], path=env.get("PATH")) or argv[0]  # leave unresolvable name to still error clearly
subprocess.run([resolved, *argv[1:]], env=env)
# also prepend your own venv bin so grandchildren see the toolchain:
env["PATH"] = str(Path(sys.executable).parent) + os.pathsep + env.get("PATH", "")

No-op on POSIX (execvpe already honours the child PATH); the fix is safe to apply unconditionally.

Key Configuration Snippets

pyproject.toml [tool.uv] settings

Full details: 03-project-config.md, 10-configuration.md

[tool.uv]
dev-dependencies = ["pytest>=8.0", "ruff>=0.5"]
python-preference = "managed"       # prefer uv-managed Python
package = false                     # treat as non-package (app)
default-groups = ["dev"]            # groups installed by default

[[tool.uv.index]]
name = "custom"
url = "https://custom.pypi.org/simple"
explicit = true                     # only use for packages that request it

[tool.uv.sources]
my-pkg = { git = "https://github.com/org/repo", tag = "v1.0" }

Workspace configuration

Full details: 12-workspaces.md

[tool.uv.workspace]
members = ["packages/*"]
exclude = ["packages/experimental"]

Dependency overrides and constraints

Full details: 05-resolution.md, 04-dependencies.md

[tool.uv]
override-dependencies = ["package==1.0.0"]
constraint-dependencies = ["package>=1.0,<2.0"]

Index configuration with authentication

Full details: 10-configuration.md, 11-authentication.md

[[tool.uv.index]]
name = "private"
url = "https://private.pypi.org/simple"

export UV_INDEX_PRIVATE_USERNAME=user
export UV_INDEX_PRIVATE_PASSWORD=token

Instructions for the Agent

1. Identify the topic from the user's question using the Command Reference or Cross-Reference tables above.
2. Read the primary doc listed for that topic. All files are at ./<filename> relative to this SKILL.md.
3. Read secondary docs from the "Also see" column or Cross-Reference table if the primary doc doesn't fully answer the question.
4. Each file is self-contained per topic - you typically need only 1-2 files per question.
5. When generating pyproject.toml configuration, cross-check with 03-project-config.md and 10-configuration.md.
6. When suggesting commands, verify flags and options against the relevant doc before recommending them.
7. For integration-specific questions (FastAPI, Jupyter, PyTorch, etc.), check 15-integrations.md first - each integration has its own ## section.

Gotcha: PEP 723 metadata is read from the HANDED file only

uv run <file> parses the # /// script block of THAT file to build the environment, before execution. It does not follow imports. So a thin launcher (uv run launcher.py where launcher.py does import report; report.main()) builds the env from the launcher's own block - absent or different - and report.py's declared dependencies are never installed. The import itself succeeds, then it dies at the first line that touches a declared dep, which points at the wrong file.

Run the script that carries the metadata, or duplicate the block into the entry file. The same applies to any indirection - runpy, an exec, a wrapper that re-dispatches.

Related, for a script SHIPPED with tests: a plain pytest imports your test module with the interpreter as-is and does NOT provision PEP 723 deps (only uv run <script> does), so a hard top-level third-party import passes under uv run and fails the gate on a clean runner. Guard it with a stdlib fallback and verify in a venv holding only pytest.

Gotcha: a missing extra is a HARD error in uv, only a warning in pip

uv pip compile --extra dev pyproject.toml fails with error: Requested extra not found: dev and exits 2 when the project declares no such extra. uv pip install -e .[dev] and pip both only warn and install the base package, so the same repo can survive the install step and then kill a later compile step in the same workflow - and a sweep across several repos dies only on the one that declares no extras.

Select the flag from what the project actually DECLARES rather than assuming a convention, since the dev set may be a PEP 735 dependency group instead of an extra:

selector = []
if "dev" in data.get("project", {}).get("optional-dependencies", {}):
    selector = ["--extra", "dev"]
elif "dev" in data.get("dependency-groups", {}):
    selector = ["--group", "dev"]