uv
All-time installs
5,800
Guide for using uv, the Python package and project manager. Use this when working with Python projects, scripts, packages, or tools.
Other options
Summary
Guide for using uv, the Python package and project manager. Use this when working with Python projects, scripts, packages, or tools.
Raw SKILL.md
4,692 bytes--- 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 # Sync the environment and update the lockfile if needed uv sync --locked # Require an up-to-date lockfile uv run <command> # Run commands in environment uv run python -c "" # Run Python in project environment uv run -p 3.12 <command> # Run with specific Python version ``` ### Tools Use `uv run` for tools declared in the project, such as `uv run pytest` or `uv run ruff check .`. This uses the project's locked tool versions and makes its dependencies available to the command. Use `uvx` for standalone tools that can run in an isolated environment. **Key commands:** ```bash uvx <tool> <args> # Run a tool in an isolated environment uvx <tool>@<version> <args> # 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. ### Type checking Use `uv check` to type check a uv project with `ty`. It syncs the project environment and uses the version of `ty` in `uv.lock` when `ty` is a project dependency or a member of the `dev` dependency group. Otherwise, uv selects a compatible version of `ty`. For a PEP 723 script, use `uv check --script script.py` to check it with its inline dependencies. ### 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 uv run --python 3.12 python -c "..." ``` Use `uvx [email protected]` when you explicitly want a standalone interpreter. ### Don't manually manage environments in uv projects ```bash # Bad python -m venv .venv source .venv/bin/activate # Good uv run <command> ``` ## 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.
Security audits
SnykPASS
SocketPASS
Gen Agent Trust HubPASS

