Verwendung
- Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
- Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
- Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/astral-sh/agent-plugins --skill uvVor dem Start
- Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
- Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.
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.lockfile - 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.lockfile) - PDM projects (identifiable by
pdm.lockfile)
Choosing the right workflow
Scripts
Use when: Running single Python files and standalone scripts.
Key commands:
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 scriptProjects
Use when: There is a pyproject.toml or uv.lock
Key commands:
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 versionTools
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:
uvx <tool> <args> # Run a tool in an isolated environment
uvx <tool>@<version> <args> # Run a specific version of a toolImportant:
uvxruns tools from PyPI by package name. This can be unsafe - only run
well-known tools.
- Only use
uv tool installonly 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:
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.txtImportant:
- Don't use the pip interface unless clearly needed.
- Don't introduce new
requirements.txtfiles. - Prefer
uv initfor new projects.
Migrating from other tools
pyenv → uv python
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 --defaultpipx → uvx
pipx run ruff → uvx ruff
pipx install ruff → uv tool install ruff
pipx upgrade ruff → uv tool upgrade ruff
pipx list → uv tool listpip and pip-tools → uv pip
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 venvCommon patterns
Don't use pip in uv projects
# Bad
pip install requests
# Good
uv add requestsDon't run python directly
# Bad
python script.py
# Good
uv run script.py# Bad
python -c "..."
# Good
uv run python -c "..."# Bad
python3.12 -c "..."
# Good
uv run --python 3.12 python -c "..."Use uvx python@3.12 when you explicitly want a standalone interpreter.
Don't manually manage environments in uv projects
# 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.