Data includes for wheels.

Each entry is a directory, whose contents are copied to the matching directory in the wheel in <name>-<version>.data/(purelib|platlib|headers|scripts|data). Upon installation, this data is moved to its target location, as defined by https://docs.python.org/3.12/library/sysconfig.html#installation-paths. Usually, small data files are included by placing them in the Python module instead of using data includes.

• scripts: Installed to the directory for executables, <venv>/bin on Unix or <venv>\Scripts on Windows. This directory is added to PATH when the virtual environment is activated or when using uv run, so this data type can be used to install additional binaries. Consider using project.scripts instead for Python entrypoints.

• data: Installed over the virtualenv environment root.

  Warning: This may override existing files!

• headers: Installed to the include directory. Compilers building Python packages with this package as build requirement use the include directory to find additional header files.

• purelib and platlib: Installed to the site-packages directory. It is not recommended to use these two options.

If set to false, the default excludes aren't applied.

Default excludes: __pycache__, *.pyc, and *.pyo.

The name of the module directory inside module-root.

The default module name is the package name with dots and dashes replaced by underscores.

Package names need to be valid Python identifiers, and the directory needs to contain a __init__.py. An exception are stubs packages, whose name ends with -stubs, with the stem being the module name, and which contain a __init__.pyi file.

For namespace packages with a single module, the path can be dotted, e.g., foo.bar or foo-stubs.bar.

For namespace packages with multiple modules, the path can be a list, e.g., ["foo", "bar"]. We recommend using a single module per package, splitting multiple packages into a workspace.

Note that using this option runs the risk of creating two packages with different names but the same module names. Installing such packages together leads to unspecified behavior, often with corrupted files or directory trees.

The directory that contains the module directory.

Common values are src (src layout, the default) or an empty path (flat layout).

Build a namespace package.

Build a PEP 420 implicit namespace package, allowing more than one root __init__.py.

Use this option when the namespace package contains multiple root __init__.py, for namespace packages with a single root __init__.py use a dotted module-name instead.

To compare dotted module-name and namespace = true, the first example below can be expressed with module-name = "cloud.database": There is one root __init__.py database. In the second example, we have three roots (cloud.database, cloud.database_pro, billing.modules.database_pro), so namespace = true is required.

src
└── cloud
    └── database
        ├── __init__.py
        ├── query_builder
        │   └── __init__.py
        └── sql
            ├── parser.py
            └── __init__.py

src
├── cloud
│   ├── database
│   │   ├── __init__.py
│   │   ├── query_builder
│   │   │   └── __init__.py
│   │   └── sql
│   │       ├── __init__.py
│   │       └── parser.py
│   └── database_pro
│       ├── __init__.py
│       └── query_builder.py
└── billing
    └── modules
        └── database_pro
            ├── __init__.py
            └── sql.py

Glob expressions which files and directories to exclude from the source distribution.

These exclusions are also applied to wheels to ensure that a wheel built from a source tree is consistent with a wheel built from a source distribution.

Glob expressions which files and directories to additionally include in the source distribution.

pyproject.toml and the contents of the module directory are always included.

Glob expressions which files and directories to exclude from the wheel.

Version of python to require when installing this group

The URL of the index.

Expects to receive a URL (e.g., <https://pypi.org/simple>) or a local path.

When uv should use authentication for requests to the index.

[[tool.uv.index]]
name = "my-index"
url = "<https://<omitted>>/simple"
authenticate = "always"

Cache control configuration for this index.

When set, these headers will override the server's cache control headers for both package metadata requests and artifact downloads.

[[tool.uv.index]]
name = "my-index"
url = "<https://<omitted>>/simple"
cache-control = { api = "max-age=600", files = "max-age=3600" }

Mark the index as the default index.

By default, uv uses PyPI as the default index, such that even if additional indexes are defined via [[tool.uv.index]], PyPI will still be used as a fallback for packages that aren't found elsewhere. To disable the PyPI default, set default = true on at least one other index.

Marking an index as default will move it to the front of the list of indexes, such that it is given the highest priority when resolving packages.

Mark the index as explicit.

Explicit indexes will only be used when explicitly requested via a [tool.uv.sources] definition, as in:

[[tool.uv.index]]
name = "pytorch"
url = "<https://download.pytorch.org/whl/cu121>"
explicit = true

[tool.uv.sources]
torch = { index = "pytorch" }

The format used by the index.

Indexes can either be PEP 503-compliant (i.e., a PyPI-style registry implementing the Simple API) or structured as a flat list of distributions (e.g., --find-links). In both cases, indexes can point to either local or remote resources.

Status codes that uv should ignore when deciding whether to continue searching in the next index after a failure.

[[tool.uv.index]]
name = "my-index"
url = "<https://<omitted>>/simple"
ignore-error-codes = [401, 403]

The name of the index.

Index names can be used to reference indexes elsewhere in the configuration. For example, you can pin a package to a specific index by name:

[[tool.uv.index]]
name = "pytorch"
url = "<https://download.pytorch.org/whl/cu121>"

[tool.uv.sources]
torch = { index = "pytorch" }

The URL of the upload endpoint.

When using uv publish --index <name>, this URL is used for publishing.

A configuration for the default index PyPI would look as follows:

[[tool.uv.index]]
name = "pypi"
url = "<https://pypi.org/simple>"
publish-url = "<https://upload.pypi.org/legacy/>"

Cache control header for Simple API requests.

Cache control header for file downloads.

The normalized name of a dependency group.

See:

• https://peps.python.org/pep-0735/
• https://packaging.python.org/en/latest/specifications/name-normalization/

Include all optional dependencies.

Only applies to pyproject.toml, setup.py, and setup.cfg sources.

Allow uv pip sync with empty requirements, which will clear the environment of all packages.

The style of the annotation comments included in the output file, used to indicate the source of each package.

Allow uv to modify an EXTERNALLY-MANAGED Python installation.

WARNING: --break-system-packages is intended for use in continuous integration (CI) environments, when installing into Python installations that are managed by an external package manager, like apt. It should be used with caution, as such Python installations explicitly recommend against modifications by other package managers (like uv or pip).

Compile Python files to bytecode after installation.

By default, uv does not compile Python (.py) files to bytecode (__pycache__/*.pyc); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.

When enabled, uv will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.

Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs.

Settings to pass to the PEP 517 build backend for specific packages, specified as KEY=VALUE pairs.

The header comment to include at the top of the output file generated by uv pip compile.

Used to reflect custom build scripts and commands that wrap uv pip compile.

Pre-defined static metadata for dependencies of the project (direct or transitive). When provided, enables the resolver to use the specified metadata instead of querying the registry or building the relevant package from source.

Metadata should be provided in adherence with the Metadata 2.3 standard, though only the following fields are respected:

• name: The name of the package.
• (Optional) version: The version of the package. If omitted, the metadata will be applied to all versions of the package.
• (Optional) requires-dist: The dependencies of the package (e.g., werkzeug>=0.14).
• (Optional) requires-python: The Python version required by the package (e.g., >=3.10).
• (Optional) provides-extra: The extras provided by the package.

Include --no-binary and --only-binary entries in the output file generated by uv pip compile.

Include --find-links entries in the output file generated by uv pip compile.

Include comment annotations indicating the index used to resolve each package (e.g., # from <https://pypi.org/simple>).

Include --index-url and --extra-index-url entries in the output file generated by uv pip compile.

Whether to emit a marker string indicating the conditions under which the set of pinned dependencies is valid.

The pinned dependencies may be valid even when the marker expression is false, but when the expression is true, the requirements are known to be correct.

Limit candidate packages to those that were uploaded prior to a given point in time.

Accepts a superset of RFC 3339 (e.g., 2006-12-02T02:07:43Z). A full timestamp is required to ensure that the resolver will behave consistently across timezones.

Limit candidate packages for specific packages to those that were uploaded prior to the given date.

Accepts package-date pairs in a dictionary format.

Include optional dependencies from the specified extra; may be provided more than once.

Only applies to pyproject.toml, setup.py, and setup.cfg sources.

Additional build dependencies for packages.

This allows extending the PEP 517 build environment for the project's dependencies with additional packages. This is useful for packages that assume the presence of packages like pip, and do not declare them as build dependencies.

Extra environment variables to set when building certain packages.

Environment variables will be added to the environment when building the specified packages.

Extra URLs of package indexes to use, in addition to --index-url.

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

All indexes provided via this flag take priority over the index specified by index_url. When multiple indexes are provided, earlier values take priority.

To control uv's resolution strategy when multiple indexes are present, see index_strategy.

Locations to search for candidate distributions, in addition to those found in the registry indexes.

If a path, the target must be a directory that contains packages as wheel files (.whl) or source distributions (e.g., .tar.gz or .zip) at the top level.

If a URL, the page must contain a flat list of links to package files adhering to the formats described above.

The strategy to use when selecting multiple versions of a given package across Python versions and platforms.

By default, uv will optimize for selecting the latest version of each package for each supported Python version (requires-python), while minimizing the number of selected versions across platforms.

Under fewest, uv will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.

Include distribution hashes in the output file.

Include the following dependency groups.

The strategy to use when resolving against multiple index URLs.

By default, uv will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (first-index). This prevents "dependency confusion" attacks, whereby an attacker can upload a malicious package under the same name to an alternate index.

The URL of the Python package index (by default: https://pypi.org/simple).

Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.

The index provided by this setting is given lower priority than any indexes specified via extra_index_url.

Attempt to use keyring for authentication for index URLs.

At present, only --keyring-provider subprocess is supported, which configures uv to use the keyring CLI to handle authentication.

The method to use when installing packages from the global cache.

Defaults to clone (also known as Copy-on-Write) on macOS and Linux, and hardlink on Windows.

WARNING: The use of symlink link mode is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (uv cache clean) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.

Exclude comment annotations indicating the source of each package from the output file generated by uv pip compile.

Don't install pre-built wheels.

The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

Don't build source distributions.

When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Alias for --only-binary :all:.

Disable isolation when building source distributions.

Assumes that build dependencies specified by PEP 518 are already installed.

Disable isolation when building source distributions for a specific package.

Assumes that the packages' build dependencies specified by PEP 518 are already installed.

Ignore package dependencies, instead only add those packages explicitly listed on the command line to the resulting requirements file.

Specify a package to omit from the output resolution. Its dependencies will still be included in the resolution. Equivalent to pip-compile's --unsafe-package option.

Exclude the specified optional dependencies if all-extras is supplied.

Exclude the comment header at the top of output file generated by uv pip compile.

Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links.

Ignore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any local or Git sources.

Ignore tool.uv.sources for the specified packages.

Include extras in the output file.

By default, uv strips extras, as any packages pulled in by the extras are already included as dependencies in the output file directly. Further, output files generated with --no-strip-extras cannot be used as constraints files in install and sync invocations.

Include environment markers in the output file generated by uv pip compile.

By default, uv strips environment markers, as the resolution generated by compile is only guaranteed to be correct for the target environment.

Only use pre-built wheels; don't build source distributions.

When enabled, resolving will not run code from the given packages. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.

Multiple packages may be provided. Disable binaries for all packages with :all:. Clear previously specified packages with :none:.

Write the requirements generated by uv pip compile to the given requirements.txt file.

If the file already exists, the existing versions will be preferred when resolving dependencies, unless --upgrade is also specified.

Install packages into lib, bin, and other top-level folders under the specified directory, as if a virtual environment were present at that location.

In general, prefer the use of --python to install into an alternate environment, as scripts and other artifacts installed via --prefix will reference the installing interpreter, rather than any interpreter added to the --prefix directory, rendering them non-portable.

The strategy to use when considering pre-release versions.

By default, uv will accept pre-releases for packages that only publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers (if-necessary-or-explicit).

The Python interpreter into which packages should be installed.

By default, uv installs into the virtual environment in the current working directory or any parent directory. The --python option allows you to specify a different interpreter, which is intended for use in continuous integration (CI) environments or other automated workflows.

Supported formats:

• 3.10 looks for an installed Python 3.10 in the registry on Windows (see py --list-paths), or python3.10 on Linux and macOS.
• python3.10 or python.exe looks for a binary with the given name in PATH.
• /home/ferris/.local/bin/python3.10 uses the exact Python at the given path.

The platform for which requirements should be resolved.

Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.

The minimum Python version that should be supported by the resolved requirements (e.g., 3.8 or 3.8.17).

If a patch version is omitted, the minimum patch version is assumed. For example, 3.8 is mapped to 3.8.0.

Reinstall all packages, regardless of whether they're already installed. Implies refresh.

Reinstall a specific package, regardless of whether it's already installed. Implies refresh-package.

Require a matching hash for each requirement.

Hash-checking mode is all or nothing. If enabled, all requirements must be provided with a corresponding hash or set of hashes. Additionally, if enabled, all requirements must either be pinned to exact versions (e.g., ==1.0.0), or be specified via direct URL.

Hash-checking mode introduces a number of additional constraints:

• Git dependencies are not supported.
• Editable installations are not supported.
• Local dependencies are not supported, unless they point to a specific wheel (.whl) or source archive (.zip, .tar.gz), as opposed to a directory.

The strategy to use when selecting between the different compatible versions for a given package requirement.

By default, uv will use the latest compatible version of each package (highest).

Validate the Python environment, to detect packages with missing dependencies and other issues.

Install packages into the system Python environment.

By default, uv installs into the virtual environment in the current working directory or any parent directory. The --system option instructs uv to instead use the first Python found in the system PATH.

WARNING: --system is intended for use in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

Install packages into the specified directory, rather than into the virtual or system Python environment. The packages will be installed at the top-level of the directory.

The backend to use when fetching packages in the PyTorch ecosystem.

When set, uv will ignore the configured index URLs for packages in the PyTorch ecosystem, and will instead use the defined backend.

For example, when set to cpu, uv will use the CPU-only PyTorch index; when set to cu126, uv will use the PyTorch index for CUDA 12.6.

The auto mode will attempt to detect the appropriate PyTorch index based on the currently installed CUDA drivers.

This setting is only respected by uv pip commands.

This option is in preview and may change in any future release.

Perform a universal resolution, attempting to generate a single requirements.txt output file that is compatible with all operating systems, architectures, and Python implementations.

In universal mode, the current Python version (or user-provided --python-version) will be treated as a lower bound. For example, --universal --python-version 3.7 would produce a universal resolution for Python 3.7 and later.

Allow package upgrades, ignoring pinned versions in any existing output file.

Allow upgrades for a specific package, ignoring pinned versions in any existing output file.

Accepts both standalone package names (ruff) and version specifiers (ruff<0.5.0).

Validate any hashes provided in the requirements file.

Unlike --require-hashes, --verify-hashes does not require that all requirements have hashes; instead, it will limit itself to verifying the hashes of those requirements that do include them.

The normalized name of a package.

Converts the name to lowercase and collapses runs of -, _, and . down to a single -. For example, ---, ., and __ are all converted to a single -.

See: https://packaging.python.org/en/latest/specifications/name-normalization/

PEP 508-style Python requirement, e.g., >=3.10

PEP 440-style package version, e.g., 1.2.3

Packages to exclude as workspace members. If a package matches both members and exclude, it will be excluded.

Supports both globs and explicit paths.

For more information on the glob syntax, refer to the glob documentation.

Packages to include as workspace members.

Supports both globs and explicit paths.

For more information on the glob syntax, refer to the glob documentation.