--- title: "Astral uv Python Workflow: review, setup & limitations · Undominated.ai" canonical: https://undominated.ai/skills/astral-uv/ description: "Establishes disciplined uv workflows across standalone scripts, lockfile-managed projects, and ephemeral CLI tool execution." --- # Astral uv Python Workflow: review, setup & limitations · Undominated.ai > Establishes disciplined uv workflows across standalone scripts, lockfile-managed projects, and ephemeral CLI tool execution. [← Explore all skills](/skills/) PACKAGE MANAGEMENT / Astral # Astral uv Python Workflow Establishes disciplined uv workflows across standalone scripts, lockfile-managed projects, and ephemeral CLI tool execution. [See setup guidance ↓](#setup)[Original source ↗](https://github.com/astral-sh/claude-code-plugins) SOURCE REVIEW Reviewed 2026-10-15 Evidence 3 linked sources Publisher Astral Licence [MIT ↗](https://github.com/astral-sh/claude-code-plugins/blob/f3ce88a7ba830f53afd6d944c1d0278ed318e142/LICENSE-MIT) Revision f3ce88a7ba83 [Read what was—and wasn’t—checked ↓](#review) “Guide for using uv, the Python package and project manager. Use this when working with Python projects, scripts, packages, or tools.” [Astral · upstream description ↗](https://github.com/astral-sh/claude-code-plugins/blob/f3ce88a7ba830f53afd6d944c1d0278ed318e142/plugins/astral/skills/uv/SKILL.md) Our analysis follows below. 01 / THE REASONING ## Why this made the selection. - The skill picks one uv workflow from scripts, projects, tools, or the pip interface instead of mixing them. - It refuses uv inside a project another tool already manages. ### A good fit for - Running a single Python script or a pyproject project with uv - Running ruff, ty, or pytest through uvx without installing them into the project - Choose uv project, script, tool or legacy pip-interface workflows from repository evidence. ### Weigh up before choosing - The skill says not to use uv in projects managed by other tools, not to call pip inside a uv project, and not to run python directly there. - The pip interface is only for legacy requirements.txt workflows that have no uv.lock. - The README at this revision dual-licenses the repository MIT or Apache-2.0, while the catalogue name is MIT alone. - This review did not execute the skill. - uvx executes fetched packages; familiar names are not a supply-chain guarantee. Running uv can resolve dependencies and change lock/environment state. 02 / THE REVIEW RECORD ## What we actually inspected. Source review has boundaries. A clear record is more useful than a “safe” badge. ### Material inspected - plugins/astral/skills/uv/SKILL.md - LICENSE-MIT - LICENSE-APACHE - README.md ### Our findings - The pinned skill says to use uv whenever uv.lock or a uv-generated requirements header is present, and not when another tool owns the project. - Scripts, projects, tools, and uv pip are four separate workflows with their own commands. - Migrations are named from pyenv to uv python, pipx to uvx, and pip-tools to uv pip. - The same revision's README says the work is licensed under either Apache-2.0 or MIT, and both LICENSE-APACHE and LICENSE-MIT are present. - The source makes project and tool workflows separate and explicitly avoids the pip interface when a uv-managed project already exists. ### Not established by this review - The skill was not executed inside a host agent. - Not executed: it was not installed or run. The review applies to the material and revision named here. A newer upstream release can change its behavior. 03 / PUT IT TO WORK ## Add a skill to your workflow. [Upstream setup instructions ↗](https://github.com/vercel-labs/skills/blob/48dc9e8eb8aa19040e91cb90ba0b642c9cbad57e/README.md) DOCUMENTED COMMAND npx skills add astral-sh/claude-code-plugins/plugins/astral/skills/uv Copy command ↗ Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above. Optional: install the reviewed revision Keeps the original source and installer version where recorded, while leaving your AI tools and installation scope for you to choose. npx skills add https://github.com/astral-sh/claude-code-plugins/tree/f3ce88a7ba830f53afd6d944c1d0278ed318e142/plugins/astral/skills/uv Copy reviewed-revision command ↗ - Install the skill into your coding agent workspace. - Install the uv CLI on your workstation: curl -LsSf https://astral.sh/uv/install.sh | sh. - For manual installation instead, download the complete bundle from https://undominated.ai/resources/skills/astral-uv/bundle.zip and extract it into a new directory. It holds SKILL.md unchanged at revision f3ce88a7, the upstream licence and an attribution file. - Place the extracted directory in your host's documented skills directory, named uv. Keep SKILL.md and the licence together. ### Before you start - Node.js runtime - uv CLI installed locally ### Compatibility Agent Skills hosts · uv 0.4+ · Python 3.8 - 3.13 ### Implementation Markdown · Python ### Python environment and project management patterns - Create environments, locks, and tool caches via uv - Read pyproject.toml, uv.lock, or requirements.txt - Network access when uv downloads packages - Creates environments, downloads dependencies and executes project/tool code; package-index credentials need normal secret handling. ### Cost model The repository offers MIT or Apache-2.0; package downloads use the indexes uv is configured to reach. THE COMPLETE REVIEWED DEFINITION ## Read it before you reuse it. Original source bytes, with attribution. Review the host-specific setup notes above. Copy definition ↗ [Download definition + licence ↗](/resources/skills/astral-uv/bundle.zip)[Raw Markdown ↗](/resources/skills/astral-uv/definition.md) --- name: uv description: Guide for using uv, the Python package and project manager. Use this when working with Python projects, scripts, packages, or tools. --- # uv uv is an extremely fast Python package and project manager. It replaces pip, pip-tools, pipx, pyenv, virtualenv, poetry, etc. ## When to use uv **Always use uv for Python work**, especially if you see: - The `uv.lock` file - uv headers in `requirements*` files, e.g., "This file was autogenerated by uv" Don't use uv in projects managed by other tools: - Poetry projects (identifiable by `poetry.lock` file) - PDM projects (identifiable by `pdm.lock` file) ## Choosing the right workflow ### Scripts **Use when:** Running single Python files and standalone scripts. **Key commands:** ```bash uv run script.py # Run a script uv run --with requests script.py # Run with additional packages uv add --script script.py requests # Add dependencies inline to the script ``` ### Projects **Use when:** There is a `pyproject.toml` or `uv.lock` **Key commands:** ```bash uv init # Create new project uv add requests # Add dependency uv remove requests # Remove dependency uv sync # Install from lockfile uv run # Run commands in environment uv run python -c "" # Run Python in project environment uv run -p 3.12 # Run with specific Python version ``` ### Tools **Use when:** Running command-line tools (e.g., ruff, ty, pytest) without installation. **Key commands:** ```bash uvx # Run a tool without installation uvx @ # Run a specific version of a tool ``` **Important:** - `uvx` runs tools from PyPI by package name. This can be unsafe - only run well-known tools. - Only use `uv tool install` only when specifically requested by the user. ### Pip interface **Use when:** Legacy workflows with `requirements.txt` or manual environment management, no `uv.lock` present. **Key commands:** ```bash uv venv uv pip install -r requirements.txt uv pip compile requirements.in -o requirements.txt uv pip sync requirements.txt # Platform independent resolution uv pip compile --universal requirements.in -o requirements.txt ``` **Important:** - Don't use the pip interface unless clearly needed. - Don't introduce new `requirements.txt` files. - Prefer `uv init` for new projects. ## Migrating from other tools ### pyenv → uv python ```bash pyenv install 3.12 → uv python install 3.12 pyenv versions → uv python list --only-installed pyenv local 3.12 → uv python pin 3.12 pyenv global 3.12 → uv python install 3.12 --default ``` ### pipx → uvx ```bash pipx run ruff → uvx ruff pipx install ruff → uv tool install ruff pipx upgrade ruff → uv tool upgrade ruff pipx list → uv tool list ``` ### pip and pip-tools → uv pip ```bash pip install package → uv pip install package pip install -r req.txt → uv pip install -r req.txt pip freeze → uv pip freeze pip-compile req.in → uv pip compile req.in pip-sync req.txt → uv pip sync req.txt virtualenv .venv → uv venv ``` ## Common patterns ### Don't use pip in uv projects ```bash # Bad pip install requests # Good uv add requests ``` ### Don't run python directly ```bash # Bad python script.py # Good uv run script.py ``` ```bash # Bad python -c "..." # Good uv run python -c "..." ``` ```bash # Bad python3.12 -c "..." # Good uvx python@3.12 -c "..." ``` ### Don't manually manage environments in uv projects ```bash # Bad python -m venv .venv source .venv/bin/activate # Good uv run ``` ## Documentation For detailed information, read the official documentation: - https://docs.astral.sh/uv/llms.txt The documentation links to specific pages for each of these workflows. The download contains SKILL.md . Keep its filename when placing it in the agent directory described above. By **Astral**. [Exact upstream source ↗](https://github.com/astral-sh/claude-code-plugins/blob/f3ce88a7ba830f53afd6d944c1d0278ed318e142/plugins/astral/skills/uv/SKILL.md) · [Licence](/resources/skills/astral-uv/LICENSE.txt) · [Attribution](/resources/skills/astral-uv/ATTRIBUTION.txt) SHA-256 6553a22dbe4251ec851e0d1952d11e801c07a8a6d9bab21e86aa8e6764d147db Read the applicable licence MIT License Copyright (c) 2025 Astral Software Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 04 / FOLLOW THE EVIDENCE ## The source trail. Our notes are separate from the original resource. Check upstream before adopting a new version. - [Astral uv skill definition ↗](https://github.com/astral-sh/claude-code-plugins/blob/f3ce88a7ba830f53afd6d944c1d0278ed318e142/plugins/astral/skills/uv/SKILL.md) Checked 2026-10-14 https://github.com/astral-sh/claude-code-plugins/blob/f3ce88a7ba830f53afd6d944c1d0278ed318e142/plugins/astral/skills/uv/SKILL.md Supports: summary, whySelected, bestFor, limitations - [Astral plugins license ↗](https://github.com/astral-sh/claude-code-plugins/blob/f3ce88a7ba830f53afd6d944c1d0278ed318e142/LICENSE-MIT) Checked 2026-10-14 https://github.com/astral-sh/claude-code-plugins/blob/f3ce88a7ba830f53afd6d944c1d0278ed318e142/LICENSE-MIT Supports: license - [2026-10-15 W25 source re-review at the existing pin ↗](https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/plugins/astral/skills/uv/SKILL.md) Checked 2026-10-15 https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/plugins/astral/skills/uv/SKILL.md Supports: upstreamDescription, review.notTested, review.reviewedAt KEEP COMPARING ## Other approaches to consider. Related by category or shared topics. These are alternatives to inspect, not a measured quality order. [### Modern Python ↗ Sets up uv, ruff and ty, and says when not to migrate an existing Python toolchain.](/skills/trailofbits-modern-python/)[### API Center management SDK ↗ Pins Microsoft's API Center Python skill, which requires DefaultAzureCredential and rejects connection strings and API keys for the management client.](/skills/microsoft-azure-mgmt-apicenter-py/)[### API Management SDK ↗ Pins Microsoft's API Management Python skill, which requires DefaultAzureCredential and rejects connection strings and API keys for the management client.](/skills/microsoft-azure-mgmt-apimanagement-py/) [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/) ## Continue your investigation - [Choose a toolkit](/tools/) - [Inspect execution hosts](/agents/) - [Check tool access](/mcp-servers/) - [Check project dependencies](/check-repo/)