{"id":235,"library":"uv","title":"uv","description":"Extremely fast Python package and project manager written in Rust by Astral. Current version is 0.11.2 (Mar 2026). Replaces pip, pip-tools, pipx, poetry, pyenv, virtualenv, and twine in a single tool. Recommended install is the standalone installer or pipx — NOT pip install uv into a project venv. uv is a CLI tool, not a Python library to import.","status":"active","version":"0.11.2","language":"python","source_language":"en","source_url":"https://docs.astral.sh/uv/","tags":["package-manager","tooling","virtual-environments","pip-replacement","python-versions","astral","rust"],"install":[{"cmd":"curl -LsSf https://astral.sh/uv/install.sh | sh","lang":"bash","label":"Standalone installer (recommended — macOS/Linux)"},{"cmd":"powershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"","lang":"bash","label":"Standalone installer (Windows)"},{"cmd":"pipx install uv","lang":"bash","label":"Via pipx (isolated, system-wide)"},{"cmd":"pip install uv","lang":"bash","label":"Via pip (not recommended — installs into current env)"},{"cmd":"brew install uv","lang":"bash","label":"Via Homebrew (macOS)"}],"dependencies":[],"imports":[{"note":"uv is a command-line tool only — there is no Python API to import. It manages packages, venvs, Python versions, and scripts from the terminal.","wrong":"# uv is NOT a Python library:\nimport uv  # ModuleNotFoundError\nfrom uv import install  # ModuleNotFoundError","symbol":"uv (CLI)","correct":"# uv is a CLI tool — not a Python library to import\n# Key commands:\n\n# Project management\nuv init myproject          # create new project\nuv add requests            # add dependency\nuv remove requests         # remove dependency\nuv sync                    # install all deps from lockfile\nuv run python script.py    # run in project venv\nuv run pytest              # run tool in project venv\n\n# Python management\nuv python install 3.12     # download and install Python\nuv python pin 3.12         # pin version for current dir\n\n# pip compatibility mode\nuv pip install requests    # fast pip replacement\nuv pip install -r requirements.txt\n\n# Tool runner (like pipx)\nuvx ruff check .           # run ruff in ephemeral env\nuvx black .                # run black without installing"}],"quickstart":{"code":"# Install uv (standalone installer)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Create a new project\nuv init myapp\ncd myapp\n\n# Add dependencies (writes to pyproject.toml + uv.lock)\nuv add fastapi uvicorn pydantic\nuv add --dev pytest ruff black\n\n# Run the project\nuv run uvicorn main:app --reload\n\n# Run tests\nuv run pytest\n\n# Sync environment from lockfile (like pip install -r)\nuv sync\n\n# Install a specific Python version\nuv python install 3.12\nuv python pin 3.12  # pins .python-version\n\n# pip compatibility (drop-in for pip)\nuv pip install requests\nuv pip install -r requirements.txt\nuv pip compile requirements.in  # like pip-tools\n\n# Run tools without installing (like pipx run)\nuvx ruff check .\nuvx black .","lang":"bash","description":"uv init creates pyproject.toml. uv add writes deps + lockfile. uv run uses the project venv."},"warnings":[{"fix":"Install globally by running \"curl -LsSf https://astral.sh/uv/install.sh | sh\" directly in your shell, or use \"pipx install uv\". If executing this from a Python script, use the subprocess module (e.g., subprocess.run([\"sh\", \"-c\", \"curl -LsSf https://astral.sh/uv/install.sh | sh\"])) to run shell commands. Only use pip install uv in CI/Docker where you need a quick install without curl.","message":"pip install uv into a project venv is not recommended. uv is a system-level tool — installing it as a project dependency is unnecessary and can cause version conflicts. Use the standalone installer or pipx.","severity":"gotcha","affected_versions":"all"},{"fix":"For project dependencies: use uv add requests. For quick pip-compatible installs: use uv pip install requests. Never mix them in the same workflow.","message":"uv pip install and uv add are different commands. uv pip install is a pip drop-in — it installs into the current environment without writing to pyproject.toml or lockfile. uv add is the project-aware command that updates pyproject.toml and uv.lock.","severity":"gotcha","affected_versions":"all"},{"fix":"In CI: run uv sync first, then uv run. Or use uv run --frozen to prevent environment creation if the lockfile is not satisfied.","message":"uv run automatically creates a virtual environment in .venv if one doesn't exist. Running uv run before uv sync in CI can produce an environment with only default dependencies, missing project extras.","severity":"gotcha","affected_versions":"all"},{"fix":"If you see TLS certificate errors after upgrading, use UV_NATIVE_TLS=1 environment variable or --native-tls flag to fall back to system TLS.","message":"TLS certificate verification changed in 0.11.1: rustls-platform-verifier replaced rustls-native-certs for certificate validation. May reject certificates previously trusted, especially on systems with custom CA certificates.","severity":"breaking","affected_versions":">= 0.11.1"},{"fix":"For one-off use: uvx ruff check . For permanent install: uv tool install ruff then ruff check .","message":"uvx is an alias for uv tool run — it runs tools in ephemeral, isolated environments. Tools installed with uv tool install persist. uvx installs and runs in a throwaway env each time.","severity":"gotcha","affected_versions":"all"},{"fix":"Always commit uv.lock. In CI, use uv sync --frozen to install exactly what's in the lockfile without updating it.","message":"uv generates uv.lock (not requirements.txt or poetry.lock). The lockfile is universal — it contains dependencies for all platforms. Committing uv.lock to version control is required for reproducible builds.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T12:10:14.877Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Install `uv` using the standalone installer (e.g., `curl -LsSf https://astral.sh/uv/install.sh | sh` for Unix-like systems) or `pipx install uv`, and ensure the installation directory (e.g., `~/.cargo/bin` or `~/.local/bin`) is added to your system's PATH.","cause":"The 'uv' executable is not installed or its installation directory is not included in your system's PATH environment variable.","error":"uv: command not found"},{"fix":"Use `uv` directly from your terminal or command prompt. Do not attempt to `import uv` in Python code.","cause":"`uv` is a standalone command-line interface (CLI) tool, not a Python library intended for direct import within Python scripts.","error":"ModuleNotFoundError: No module named 'uv'"},{"fix":"Ensure a Python interpreter is installed and its location is included in your system's PATH. Alternatively, specify the Python interpreter explicitly using `uv venv --python python3.10` or `uv python --version 3.10`.","cause":"`uv` could not locate a Python interpreter in your system's PATH or through common Python version managers (like pyenv, asdf, or conda), which is necessary for creating and managing virtual environments.","error":"Failed to find a Python interpreter"},{"fix":"Install `uv` using the standalone installer (download from astral.sh/uv) or `pipx install uv`. After installation, ensure the directory containing `uv.exe` (often `C:\\Users\\<YourUser>\\.cargo\\bin` or `C:\\Users\\<YourUser>\\AppData\\Roaming\\Python\\Scripts`) is added to your system's PATH.","cause":"On Windows, the 'uv' executable is not installed or its directory is not added to the system's PATH environment variable.","error":"`'uv' is not recognized as an internal or external command, operable program or batch file.`"}],"ecosystem":"pypi","meta_description":null,"install_score":80,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"18.5M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"20.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"12.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"11.9M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"18.0M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"19M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}