# Coding Python Uv > 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. - Skill: `bitranox/coding-python-uv` (Agent Skill, multi-file: 23 files) - Install (CLI): `npx skillmds@latest add bitranox/coding-python-uv` - Raw SKILL.md: https://api.skillmd.com/api/skills/bitranox/coding-python-uv/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: bitranox (https://skillmd.com/u/bitranox) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/bitranox/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 | 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__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__USERNAME` | Index auth username | `11-authentication.md` | | `UV_INDEX__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: ```bash 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]`. ```python # 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` ```toml [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` ```toml [tool.uv.workspace] members = ["packages/*"] exclude = ["packages/experimental"] ``` ### Dependency overrides and constraints Full details: `05-resolution.md`, `04-dependencies.md` ```toml [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` ```toml [[tool.uv.index]] name = "private" url = "https://private.pypi.org/simple" ``` ```bash 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 `./` 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 ` 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