DOCSEARCHbyAlgolia
Submit Docs

uv

repository·main·Indexed 13 days ago

https://github.com/astral-sh/uv

An extremely fast Python package and project manager written in Rust. It serves as a single-tool replacement for pip, pip-tools, pipx, poetry, pyenv, and virtualenv. Version 0.12.3 includes modular Rust crates for dependency resolution (uv-resolver), virtual environment management (uv-virtualenv), and PEP compliance (PEP 440, 508, 425, 517).

Tokens
179.4K
Snippets
733
Records
1K
Agent score
97%

What's inside uv

  2. Overview of uv crates

    main
    The uv repository is composed of several specialized Rust crates that power the uv package manager. These crates handle core responsibilities such as dependency resolution, virtual environment management, PEP compliance (PEP 440, 508, 425, 517), and interaction with PyPI-compatible APIs. Developers building on top of or extending uv can leverage these modular components for specific tasks like parsing distribution filenames, managing caches, or interacting with the filesystem and Git.

  3. Use uv-build as a build backend

    main
    The uv-build package is a specialized, slimmed-down version of uv that contains only the build backend logic. It is intended to be used as a PEP 517 build backend for Python projects. For general usage of uv (package management, environment handling, etc.), use the main uv package instead.

  4. Use the uv pip interface as a replacement for pip and pip-tools

    main

    The uv pip interface provides a drop-in replacement for common pip, pip-tools, and virtualenv commands. Unlike uv's primary interfaces which manage virtual environments automatically, uv pip commands work directly with existing virtual environments. This is intended for power users or projects that need low-level control without transitioning to uv's higher-level project management workflows.

    Key capabilities include:

    • Creating and using environments
    • Installing and managing packages
    • Inspecting environments and packages
    • Declaring package dependencies
    • Locking and syncing environments

    Important Note: uv does not rely on or invoke pip. The interface is named uv pip to provide a familiar command structure for low-level operations, but it is a distinct implementation. Because it does not exactly implement the behavior of the tools it replaces, you should consult the pip-compatibility guide if you encounter unexpected behavior.

  5. Use uv-virtualenv to create Python virtual environments

    main
    uv-virtualenv is a Rust library and CLI tool designed for creating Python virtual environments. It aims to maintain compatibility with the pypa/virtualenv project's activation scripts while providing specific enhancements like relocatability.

  6. Choose the right uv Docker image

    main

    uv provides two types of Docker images:

    1. Distroless images: Contain only the uv and uvx binaries. These are ideal for multi-stage builds where you copy the binaries into your own custom image.

      • ghcr.io/astral-sh/uv:latest
      • ghcr.io/astral-sh/uv:{major}.{minor}.{patch} (e.g., ghcr.io/astral-sh/uv:0.12.3)
      • ghcr.io/astral-sh/uv:{major}.{minor} (e.g., ghcr.io/astral-sh/uv:0.12)

    2. Derived images: Include an operating system with uv pre-installed. These are useful for running uv directly in a container.

      • Alpine-based: ghcr.io/astral-sh/uv:alpine, ghcr.io/astral-sh/uv:alpine3.23, etc.
      • Debian-based: ghcr.io/astral-sh/uv:debian-slim, ghcr.io/astral-sh/uv:trixie-slim, etc.
      • Python-specific: ghcr.io/astral-sh/uv:python3.12-alpine, ghcr.io/astral-sh/uv:python3.12-trixie, etc.

    Derived images use the tag format ghcr.io/astral-sh/uv:{version}-{base} (e.g., ghcr.io/astral-sh/uv:0.12.3-alpine).

    Starting with version 0.8, derived images set UV_TOOL_BIN_DIR to /usr/local/bin to support uv tool install for the default user.

  7. How forking handles environment markers

    main

    To support packages that have contradictory requirements for different environments (e.g., different numpy versions for different python_version values), uv uses a forking resolver.

    How Forking Works:

    • When a package has multiple requirements with different markers, uv splits the resolution into multiple forks.
    • Each fork represents a specific subset of the marker space (e.g., one fork for python_version >= "3.11" and another for python_version < "3.11").
    • Forks can be nested and are merged if they contain identical packages to maintain efficiency.
    • Stability: To prevent different resolution results on subsequent runs, uv writes the resolution-markers of each fork and any diverging packages to the uv.lock file. This ensures that the same forks are used in future resolutions.

    Observing Forking:

    You can see forking in action by running uv lock with the verbose flag:

    uv lock -v

    Look for log messages such as:

    • Splitting resolution on ...
    • Solving split ... (requires-python: ...)
    • Split ... resolution took ...

  8. Understand dependency resolution in uv

    main

    Resolution is the process of converting a list of requirements into a specific list of package versions that satisfy all constraints. This involves recursively searching for compatible versions of both direct dependencies (defined by your project) and transitive dependencies (dependencies of your dependencies).

    When multiple valid solutions exist (e.g., different combinations of package versions that satisfy all requirements), the resolver selects a valid set. If requirements conflict (e.g., two packages requiring incompatible versions of the same library), the resolution will fail.

  9. Configure group-specific Python version requirements

    main

    While dependency groups must generally be compatible with the project's requires-python range, you can specify a different requirement for a specific group using [tool.uv.dependency-groups]. This is useful if a development tool requires a newer Python version than the project itself supports.

    [project]
name = "example"
version = "0.0.0"
requires-python = ">=3.10"

[dependency-groups]
dev = ["pytest"]

[tool.uv.dependency-groups]
dev = {requires-python = ">=3.12"}

  10. Understand the node types in the `uv` dependency graph

    main

    The uv dependency graph consists of nodes identified by opaque ids. Nodes are categorized into five kind types:

    • "script": A PEP 723 script and its direct dependencies.
    • "workspace": A workspace root and its workspace-exclusive dependency groups.
    • "package": The package itself (includes info on sdist, wheels, extras, and dependency groups).
    • { "extra": "extraname" }: An extra defined by a package (e.g., mypackage[myextra]). These nodes always depend on the parent package node.
    • { "group": "groupname" }: A dependency group defined by a package or workspace root. Unlike extras, these nodes do not depend on the parent package.

    How to find specific nodes:

    • To install a package: Find the node where kind == "package".
    • To install an extra: Find the node where kind == { "extra": "extraname" }.
    • To install a dependency group: Find the node where kind == { "group": "groupname" }.

  11. Use automatic Hugging Face authentication

    main

    uv provides automatic authentication for the Hugging Face Hub. If the HF_TOKEN environment variable is present in your environment, uv will automatically propagate it to all requests made to huggingface.co. This allows you to seamlessly access private scripts or datasets hosted on Hugging Face.

    To disable this automatic behavior, set the UV_NO_HF_TOKEN environment variable to 1.

    # Run a script from a private Hugging Face dataset using an HF_TOKEN
HF_TOKEN=hf_... uv run https://huggingface.co/datasets/<user>/<name>/resolve/<branch>/main.py

  12. Understand uv platform support tiers

    main

    uv categorizes platform support into three tiers, which determines the level of testing and availability of official binaries:

    • Tier 1 (Guaranteed to work): Continuously built, tested, and developed against these platforms. Official binaries and PyPI wheels are provided.

      • macOS (Apple Silicon)
      • macOS (x86_64)
      • Linux (x86_64)
      • Windows (x86_64)

    • Tier 2 (Guaranteed to build): Continuously built, but the test suite is not run on them, so stability may vary. Official binaries and PyPI wheels are provided.

      • Linux (PPC64LE, RISC-V64, aarch64, armv7, i686, s390x)
      • Windows (arm64)

    • Tier 3 (Best effort): May not be built or tested, but uv accepts patches to fix bugs.

      • FreeBSD (x86_64)
      • Windows (i686)