coding-python-uv

name

coding-python-uv

description

Use when writing, configuring, debugging, or deploying Python projects that use uv as the package manager, virtual environment manager, Python version manager, or pip replacement. Covers project setup, dependency management, lockfiles, scripts, tools, building, publishing, Docker, CI/CD, authentication, caching, and migration from pip/pip-tools. Baseline is uv 0.10.2 (2026-02-12); the Python-version behaviours in 06-python-versions.md are measured on 0.11.x.

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

Command	What it does	Primary doc	Also see
uv init	Create a new project	02-projects.md
uv add / uv remove	Add/remove dependencies	04-dependencies.md	05-resolution.md
uv sync	Sync environment to lockfile	02-projects.md	04-dependencies.md
uv lock	Update the lockfile	04-dependencies.md	05-resolution.md
uv run	Run a command in the project env	02-projects.md	07-tools-and-scripts.md
uv build	Build sdist/wheel	08-building-and-publishing.md
uv publish	Publish to PyPI	08-building-and-publishing.md	11-authentication.md
uv export	Export lockfile (requirements.txt, pylock.toml, CycloneDX)	04-dependencies.md	09-pip-interface.md
uv python install	Install Python versions	06-python-versions.md
uv python list	List available/installed Pythons	06-python-versions.md
uv python pin	Pin Python version for project	06-python-versions.md	10-configuration.md
uv python find	Find a Python interpreter	06-python-versions.md
uv tool run / uvx	Run a tool in isolation	07-tools-and-scripts.md
uv tool install	Install a tool globally	07-tools-and-scripts.md
uv tool list	List installed tools	07-tools-and-scripts.md
uv venv	Create a virtual environment	09-pip-interface.md
uv pip install	Install packages (pip compat)	09-pip-interface.md
uv pip compile	Lock requirements (pip compat)	09-pip-interface.md	05-resolution.md
uv pip sync	Sync env to requirements.txt	09-pip-interface.md
uv pip uninstall	Remove packages (pip compat)	09-pip-interface.md
uv pip freeze	Output installed packages	09-pip-interface.md
uv pip list	List installed packages	09-pip-interface.md
uv pip show	Show package details	09-pip-interface.md
uv pip tree	Show dependency tree	09-pip-interface.md
uv pip check	Verify env consistency	09-pip-interface.md
uv cache clean	Clear cache	10-configuration.md
uv cache prune	Remove unused cache entries	10-configuration.md
uv version	View/bump project version	02-projects.md	08-building-and-publishing.md
uv tree	Show project dependency tree	02-projects.md
uv auth login / uv auth logout	Manage index credentials	11-authentication.md
uv auth token	Print stored auth token	11-authentication.md
uv python uninstall	Remove managed Python versions	06-python-versions.md
uv python upgrade	Upgrade Python patch version	06-python-versions.md
uv tool upgrade	Upgrade installed tools	07-tools-and-scripts.md
uv tool uninstall	Remove an installed tool	07-tools-and-scripts.md
uv tool update-shell	Update shell PATH for tools	07-tools-and-scripts.md
uv cache dir / uv tool dir / uv python dir	Show storage directories	01-getting-started.md	10-configuration.md
uv self update	Update uv itself	01-getting-started.md
uv self version	Show uv's own version	01-getting-started.md

---

Document Index

#	File	Contents
01	01-getting-started.md	Feature overview, installation methods (standalone, pip, pipx, Homebrew, Conda, Docker, etc.), shell completion, self-update, uninstallation, installer env vars (UV_INSTALL_DIR, UV_NO_MODIFY_PATH), first-steps tutorial, getting help
02	02-projects.md	Project creation (uv init), templates (--app, --lib, --package), project layout (flat vs src), running commands (uv run, --with, --no-project), syncing environments (uv sync, --frozen, --locked, --group, --only-group, --inexact), uv version (view/bump), uv tree
03	03-project-config.md	[project] table (name, version, requires-python, scripts, entry-points, gui-scripts), [tool.uv] settings (dev-dependencies, managed, package, python-preference, default-groups, environments), build systems, project packaging
04	04-dependencies.md	uv add/uv remove, dependency groups (--group dev), optional deps (--optional), platform-specific deps, source deps (git, path, URL, editable, workspace), uv lock, constraints ([tool.uv.constraint-dependencies]), uv export to requirements.txt/pylock.toml/CycloneDX (--no-hashes, --group, --all-groups, --format)
05	05-resolution.md	Resolution strategies (--resolution lowest/lowest-direct/highest), pre-release handling (--prerelease), dependency overrides ([tool.uv.override-dependencies]), constraints, --exclude-newer / UV_EXCLUDE_NEWER, platform-specific resolution, reproducibility, forking resolver
06	06-python-versions.md	uv python install/list/find/pin, version request syntax, discovery order, .python-version/.python-versions files, python-downloads setting, UV_PYTHON, UV_PYTHON_PREFERENCE, requires-python, PyPy support
07	07-tools-and-scripts.md	Tools: uv tool run/uvx, --from, --with, version requests, uv tool install/list/upgrade/uninstall/update-shell/dir, tool directories and PATH. Scripts: uv run script.py, PEP 723 inline metadata (# /// script), uv init --script, uv add --script, shebangs
08	08-building-and-publishing.md	uv build (sdists, wheels, --sdist, --wheel, --out-dir, --package), uv's build backend (uv_build), [build-system] config, [tool.uv.build-backend] settings, uv publish, trusted publishers (PyPI/GitHub OIDC), token auth, --publish-url
09	09-pip-interface.md	uv venv (creating envs, --python, --system), uv pip install/uninstall (PyPI, git, URLs, --system, --target, --prefix, editable), uv pip compile/sync (pip-tools workflow), uv pip show/list/tree/check/freeze, dependency formats (requirements.txt, pyproject.toml, setup.py), pip compatibility differences
10	10-configuration.md	Config files (pyproject.toml [tool.uv], uv.toml, .python-version), precedence (CLI > env > project > user), package indexes (--index, --default-index, [[tool.uv.index]], --index-strategy, per-package pinning), cache (uv cache clean/prune, UV_CACHE_DIR, --no-cache), preview features (--preview, UV_PREVIEW), storage locations (UV_CACHE_DIR, UV_TOOL_DIR, UV_PYTHON_INSTALL_DIR)
11	11-authentication.md	uv auth login/logout/token, HTTP auth (credentials in URLs, .netrc, keyring --keyring-provider, UV_INDEX_<NAME>_USERNAME/PASSWORD), Git auth (SSH, credential helpers, GitHub/GitLab tokens), insecure hosts (--allow-insecure-host), TLS/SSL (--cert, SSL_CERT_FILE, SSL_CLIENT_CERT), third-party indexes (Google Artifact Registry, AWS CodeArtifact, Azure Artifacts, Hugging Face, JFrog Artifactory)
12	12-workspaces.md	Monorepo/multi-package projects: [tool.uv.workspace] with members/exclude, workspace root, path dependencies, shared lockfile, --package flag
13	13-docker.md	Docker integration: multi-stage builds, installing uv (ghcr.io image, pip, copy from stage), UV_COMPILE_BYTECODE, UV_LINK_MODE, layer caching strategies, non-root users, best practices
14	14-ci-cd.md	GitHub Actions: setup-uv action, caching, Python version matrix. GitLab CI/CD: configuration examples, caching, Docker pipelines
15	15-integrations.md	FastAPI, Jupyter, Marimo, pre-commit, PyTorch/CUDA indexes (--torch-backend), AWS Lambda (packaging, Docker, layers), alternative indexes ([[tool.uv.index]]), dependency bots (Renovate, Dependabot), Coiled (Dask)
16	16-migration.md	Migrating from pip + requirements.txt to uv projects: converting requirements, creating pyproject.toml, handling constraints files, replacing pip-tools workflows
17	17-troubleshooting.md	Build failures (missing system libs, C compiler, --no-build-isolation), reproducible examples for bug reports, supported platforms matrix (Linux, macOS, Windows, musl/glibc, aarch64, x86_64, etc.)

---

Cross-Reference by Scenario

Scenario	Read these docs
"Set up a new Python project"	02-projects.md, 03-project-config.md
"Add a dependency"	04-dependencies.md, 05-resolution.md
"Add a dev dependency"	04-dependencies.md (search: dependency groups, --group dev)
"Pin Python version"	06-python-versions.md, 10-configuration.md
"Use a private package index"	10-configuration.md, 11-authentication.md, 15-integrations.md (Alternative Indexes section)
"Docker build with uv"	13-docker.md, 01-getting-started.md
"GitHub Actions CI"	14-ci-cd.md
"GitLab CI"	14-ci-cd.md
"Deploy to AWS Lambda"	15-integrations.md (AWS Lambda section), 04-dependencies.md
"Migrate from pip/requirements.txt"	16-migration.md, 09-pip-interface.md
"Use pip-tools workflow (compile/sync)"	09-pip-interface.md
"Monorepo / workspace"	12-workspaces.md, 04-dependencies.md
"Run a one-off tool (like ruff, black)"	07-tools-and-scripts.md (Tools section)
"Run a script with inline deps"	07-tools-and-scripts.md (Scripts section)
"Build and publish a package"	08-building-and-publishing.md, 11-authentication.md
"Configure resolution (pre-releases, overrides)"	05-resolution.md, 04-dependencies.md
"Use PyTorch / CUDA indexes"	15-integrations.md (PyTorch section), 10-configuration.md
"Jupyter notebook with uv"	15-integrations.md (Jupyter section)
"FastAPI project"	15-integrations.md (FastAPI section), 02-projects.md
"SSL/TLS certificate issues"	11-authentication.md, 17-troubleshooting.md
"Build failures / missing C libs"	17-troubleshooting.md, 10-configuration.md
"Cache problems / disk space"	10-configuration.md (Cache and Storage sections)
"Lock reproducibility / --exclude-newer"	05-resolution.md, 02-projects.md
"pre-commit hooks"	15-integrations.md (pre-commit section)
"Dependency update bots"	15-integrations.md (Dependency Bots section)
"Export lockfile (requirements.txt, pylock.toml, CycloneDX)"	04-dependencies.md (Export section), 09-pip-interface.md
"Editable installs"	09-pip-interface.md, 04-dependencies.md
"Using system Python / --system"	09-pip-interface.md, 06-python-versions.md
"View or bump project version"	02-projects.md, 08-building-and-publishing.md
"Manage index credentials (login/logout)"	11-authentication.md
"Export SBOM (CycloneDX)"	04-dependencies.md (Export section)
"Marimo notebooks with uv"	15-integrations.md (Marimo section)
"Hugging Face model index"	11-authentication.md
"Build isolation issues (flash-attn, deepspeed)"	03-project-config.md, 17-troubleshooting.md

---

Key Environment Variables

Variable	Purpose	Doc
UV_CACHE_DIR	Override cache directory	10-configuration.md
UV_TOOL_DIR	Override tool install directory	10-configuration.md
UV_PYTHON_INSTALL_DIR	Override managed Python directory	10-configuration.md
UV_PYTHON	Override Python interpreter	06-python-versions.md
UV_PYTHON_PREFERENCE	Prefer managed vs system Python	06-python-versions.md
UV_SYSTEM_PYTHON	Use system Python by default	14-ci-cd.md
UV_PREVIEW	Enable preview features	10-configuration.md
UV_EXCLUDE_NEWER	Exclude packages after date	05-resolution.md
UV_INDEX_<NAME>_USERNAME	Index auth username	11-authentication.md
UV_INDEX_<NAME>_PASSWORD	Index auth password/token	11-authentication.md
UV_INSTALL_DIR	Override uv install location	01-getting-started.md
UV_COMPILE_BYTECODE	Compile .pyc during install	13-docker.md
UV_LINK_MODE	Install link mode (copy/hardlink)	13-docker.md
SSL_CERT_FILE	Custom CA certificate bundle	11-authentication.md
SSL_CLIENT_CERT	Client TLS certificate	11-authentication.md

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.