By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a
+reliable set of trust roots from Mozilla, and including them in uv improves portability and
+performance (especially on macOS, where reading the system trust store incurs a significant delay).
In some cases, you may want to use the platform's native certificate store, especially if you're
+relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's
+certificate store. To instruct uv to use the system's trust store, run uv with the --native-tls
+command-line flag, or set the UV_NATIVE_TLS environment variable to true.
If a direct path to the certificate is required (e.g., in CI), set the SSL_CERT_FILE environment
+variable to the path of the certificate bundle, to instruct uv to use that file instead of the
+system's trust store.
If client certificate authentication (mTLS) is desired, set the SSL_CLIENT_CERT environment
+variable to the path of the PEM formatted file containing the certificate followed by the private
+key.
If you're using a setup in which you want to trust a self-signed certificate or otherwise disable
+certificate verification, you can instruct uv to allow insecure connections to dedicated hosts via
+the allow-insecure-host configuration option. For example, adding the following to
+pyproject.toml will allow insecure connections to example.com:
allow-insecure-host expects to receive a hostname (e.g., localhost) or hostname-port pair (e.g.,
+localhost:8080), and is only applicable to HTTPS connections, as HTTP connections are inherently
+insecure.
Use allow-insecure-host with caution and only in trusted environments, as it can expose you to
+security risks due to the lack of certificate verification.
uv auth CLIuv provides a high-level interface for storing and retrieving credentials from services.
+To add credentials for service, use the uv auth login command:
This will prompt for the credentials.
+The credentials can also be provided using the --username and --password options, or the
+--token option for services which use a __token__ or arbitrary username.
Note
+We recommend providing the secret via stdin. Use - to indicate the value should be read from
+stdin, e.g., for --password:
The same pattern can be used with --token.
Once credentials are added, uv will use them for packaging operations that require fetching content +from the given service. At this time, only HTTPS Basic authentication is supported. The credentials +will not yet be used for Git requests.
+Note
+The credentials will not be validated, i.e., incorrect credentials will not fail.
+To remove credentials, use the uv auth logout command:
Note
+The credentials will not be invalidated with the remote server, i.e., they will only be removed +from local storage not rendered unusable.
+To show the credential stored for a given URL, use the uv auth token command:
If a username was used to log in, it will need to be provided as well, e.g.:
+ +Credentials are persisted to the uv credentials store.
+By default, credentials are written to a plaintext file. An encrypted system-native storage backend
+can be enabled with UV_PREVIEW_FEATURES=native-auth.
uv allows packages to be installed from private Git repositories using SSH or HTTP authentication.
+To authenticate using an SSH key, use the ssh:// protocol:
git+ssh://git@<hostname>/... (e.g., git+ssh://git@github.com/astral-sh/uv)git+ssh://git@<host>/... (e.g., git+ssh://git@github.com-key-2/astral-sh/uv)SSH authentication requires using the username git.
See the +GitHub SSH documentation +for more details on how to configure SSH.
+To authenticate over HTTP Basic authentication using a password or token:
+git+https://<user>:<token>@<hostname>/... (e.g.,
+ git+https://git:github_pat_asdf@github.com/astral-sh/uv)git+https://<token>@<hostname>/... (e.g., git+https://github_pat_asdf@github.com/astral-sh/uv)git+https://<user>@<hostname>/... (e.g., git+https://git@github.com/astral-sh/uv)Note
+When using a GitHub personal access token, the username is arbitrary. GitHub doesn't allow you to +use your account name and password in URLs like this, although other hosts may.
+If there are no credentials present in the URL and authentication is needed, the +Git credential helper will be queried.
+When using uv add, uv will not persist Git credentials to the pyproject.toml or uv.lock.
+These files are often included in source control and distributions, so it is generally unsafe to
+include credentials in them.
If you have a Git credential helper configured, your credentials may be automatically persisted, +resulting in successful subsequent fetches of the dependency. However, if you do not have a Git +credential helper or the project is used on a machine without credentials seeded, uv will fail to +fetch the dependency.
+You may force uv to persist Git credentials by passing the --raw option to uv add. However, we
+strongly recommend setting up a credential helper instead.
Git credential helpers are used to store and retrieve Git credentials. See the +Git documentation to learn more.
+If you're using GitHub, the simplest way to set up a credential helper is to
+install the gh CLI and use:
See the gh auth login documentation for more
+details.
Note
+When using gh auth login interactively, the credential helper will be configured automatically.
+But when using gh auth login --with-token, as in the uv
+GitHub Actions guide, the
+gh auth setup-git command will need to be
+run afterwards to configure the credential helper.
uv supports credentials over HTTP when querying package registries.
+Authentication can come from the following sources, in order of precedence:
+https://<user>:<password>@<hostname>/...Authentication may be used for hosts specified in the following contexts:
+[index]index-urlextra-index-urlfind-linkspackage @ https://....netrc files are a long-standing plain text format
+for storing credentials on a system.
Reading credentials from .netrc files is always enabled. The target file path will be loaded from
+the NETRC environment variable if defined, falling back to ~/.netrc if not.
uv can read and write credentials from a store using the uv auth commands.
Credentials are stored in a plaintext file in uv's state directory, e.g.,
+~/.local/share/uv/credentials/credentials.toml on Unix. This file is currently not intended to be
+edited manually.
Note
+A secure, system native storage mechanism is in preview — it is still +experimental and being actively developed. In the future, this will become the default storage +mechanism.
+When enabled, uv will use the secret storage mechanism native to your operating system. On +macOS, it uses the Keychain Services. On Windows, it uses the Windows Credential Manager. On +Linux, it uses the DBus-based Secret Service API.
+Currently, uv only searches the native store for credentials it has added to the secret store — +it will not retrieve credentials persisted by other applications.
+Set UV_PREVIEW_FEATURES=native-auth to use this storage mechanism.
A keyring provider is a concept from pip allowing retrieval of credentials from an interface
+matching the popular keyring Python package.
The "subprocess" keyring provider invokes the keyring command to fetch credentials. uv does not
+support additional keyring provider types at this time.
Set --keyring-provider subprocess, UV_KEYRING_PROVIDER=subprocess, or
+tool.uv.keyring-provider = "subprocess" to use the provider.
If authentication is found for a single index URL or net location (scheme, host, and port), it will +be cached for the duration of the command and used for other queries to that index or net location. +Authentication is not cached across invocations of uv.
+When using uv add, uv will not persist index credentials to the pyproject.toml or uv.lock.
+These files are often included in source control and distributions, so it is generally unsafe to
+include credentials in them. However, uv will persist credentials for direct URLs, i.e.,
+package @ https://username:password:example.com/foo.whl, as there is not currently a way to
+otherwise provide those credentials.
If credentials were attached to an index URL during uv add, uv may fail to fetch dependencies from
+indexes which require authentication on subsequent operations. See the
+index authentication documentation for details on persistent
+authentication for indexes.
See the index authentication documentation for details on +authenticating index URLs.
+See the pip compatibility guide for details
+on differences from pip.
Authentication is required when working with private repositories or package indexes.
+Learn more about authentication in uv:
+ + + + + + + + + + + + + + + + + + +See the alternative indexes integration guide for +details on authentication with popular alternative Python package indexes.
+uv supports automatic authentication for the Hugging Face Hub. Specifically, if the HF_TOKEN
+environment variable is set, uv will propagate it to requests to huggingface.co.
This is particularly useful for accessing private scripts in Hugging Face Datasets. For example, you
+can run the following command to execute the script main.py script from a private dataset:
You can disable automatic Hugging Face authentication by setting the UV_NO_HF_TOKEN=1 environment
+variable.
A build backend transforms a source tree (i.e., a directory) into a source distribution or a wheel.
+uv supports all build backends (as specified by PEP 517), but
+also provides a native build backend (uv_build) that integrates tightly with uv to improve
+performance and user experience.
The uv build backend is a great choice for most Python projects. It has reasonable defaults, with +the goal of requiring zero configuration for most users, but provides flexible configuration to +accommodate most Python project structures. It integrates tightly with uv, to improve messaging and +user experience. It validates project metadata and structures, preventing common mistakes. And, +finally, it's very fast.
+The uv build backend currently only supports pure Python code. An alternative backend is +required to build a +library with extension modules.
+Tip
+While the backend supports a number of options for configuring your project structure, when build scripts or +a more flexible project layout are required, consider using the +hatchling build backend instead.
+To use uv as a build backend in an existing project, add uv_build to the
+[build-system] section in your pyproject.toml:
Note
+The uv build backend follows the same versioning policy
+as uv. Including an upper bound on the uv_build version ensures that your package continues to
+build correctly as new versions are released.
To create a new project that uses the uv build backend, use uv init:
When the project is built, e.g., with uv build, the uv build backend will
+be used to create the source distribution and wheel.
The build backend is published as a separate package (uv_build) that is optimized for portability
+and small binary size. However, the uv executable also includes a copy of the build backend, which
+will be used during builds performed by uv, e.g., during uv build, if its version is compatible
+with the uv_build requirement. If it's not compatible, a compatible version of the uv_build
+package will be used. Other build frontends, such as python -m build, will always use the
+uv_build package, typically choosing the latest compatible version.
Python packages are expected to contain one or more Python modules, which are directories containing
+an __init__.py. By default, a single root module is expected at src/<package_name>/__init__.py.
For example, the structure for a project named foo would be:
uv normalizes the package name to determine the default module name: the package name is lowercased
+and dots and dashes are replaced with underscores, e.g., Foo-Bar would be converted to foo_bar.
The src/ directory is the default directory for module discovery.
These defaults can be changed with the module-name and module-root settings. For example, to use
+a FOO module in the root directory, as in the project structure:
The correct build configuration would be:
+ +Namespace packages are intended for use-cases where multiple packages write modules into a shared +namespace.
+Namespace package modules are identified by a . in the module-name. For example, to package the
+module bar in the shared namespace foo, the project structure would be:
And the module-name configuration would be:
Important
+The __init__.py file is not included in foo, since it's the shared namespace module.
It's also possible to have a complex namespace package with more than one root module, e.g., with +the project structure:
+ +While we do not recommend this structure (i.e., you should use a workspace with multiple packages
+instead), it is supported by setting module-name to a list of names:
For packages with many modules or complex namespaces, the namespace = true option can be used to
+avoid explicitly declaring each module name, e.g.:
Warning
+Using namespace = true disables safety checks. Using an explicit list of module names is
+strongly recommended outside of legacy projects.
The namespace option can also be used with module-name to explicitly declare the root, e.g., for
+the project structure:
The recommended configuration would be:
+ +The build backend also supports building type stub packages, which are identified by the -stubs
+suffix on the package or module name, e.g., foo-stubs. The module name for type stub packages must
+end in -stubs, so uv will not normalize the - to an underscore. Additionally, uv will search for
+a __init__.pyi file. For example, the project structure would be:
Type stub modules are also supported for namespace packages.
+The build backend is responsible for determining which files in a source tree should be packaged +into the distributions.
+To determine which files to include in a source distribution, uv first adds the included files and +directories, then removes the excluded files and directories. This means that exclusions always take +precedence over inclusions.
+By default, uv excludes __pycache__, *.pyc, and *.pyo.
When building a source distribution, the following files and directories are included:
+pyproject.tomltool.uv.build-backend.module-root.project.license-files and project.readme.tool.uv.build-backend.data.tool.uv.build-backend.source-include.From these, items matching
+tool.uv.build-backend.source-exclude and
+the default excludes are removed.
When building a wheel, the following files and directories are included:
+tool.uv.build-backend.module-rootproject.license-files, which are copied into the .dist-info directory.project.readme, which is copied into the project metadata.tool.uv.build-backend.data,
+ which are copied into the .data directory.From these,
+tool.uv.build-backend.source-exclude,
+tool.uv.build-backend.wheel-exclude and
+the default excludes are removed. The source dist excludes are applied to avoid source tree to wheel
+source builds including more files than source tree to source distribution to wheel build.
There are no specific wheel includes. There must only be one top level module, and all data files +must either be under the module root or in the appropriate +data directory. Most packages store small data in the +module root alongside the source code.
+Tip
+When using the uv build backend through a frontend that is not uv, such as pip or
+python -m build, debug logging can be enabled through environment variables with
+RUST_LOG=uv=debug or RUST_LOG=uv=verbose. When used through uv, the uv build backend shares
+the verbosity level of uv.
Includes are anchored, which means that pyproject.toml includes only <root>/pyproject.toml and
+not <root>/bar/pyproject.toml. To recursively include all files under a directory, use a /**
+suffix, e.g. src/**. Recursive inclusions are also anchored, e.g., assets/**/sample.csv includes
+all sample.csv files in <root>/assets or any of its children.
Note
+For performance and reproducibility, avoid patterns without an anchor such as **/sample.csv.
Excludes are not anchored, which means that __pycache__ excludes all directories named
+__pycache__ regardless of its parent directory. All children of an exclusion are excluded as well.
+To anchor a directory, use a / prefix, e.g., /dist will exclude only <root>/dist.
All fields accepting patterns use the reduced portable glob syntax from +PEP 639, with the addition that +characters can be escaped with a backslash.
+ + + + + + + + + + + + + + + + + +uv uses aggressive caching to avoid re-downloading (and re-building) dependencies that have already +been accessed in prior runs.
+The specifics of uv's caching semantics vary based on the nature of the dependency:
+uv pip compile will pin Git dependencies to a specific commit hash when writing the resolved
+ dependency set..whl or .tar.gz file). For directories, uv caches based on the last-modified time of
+ the pyproject.toml, setup.py, or setup.cfg file.If you're running into caching issues, uv includes a few escape hatches:
+uv cache clean. To clear the cache for a specific package, run
+ uv cache clean <package-name>. For example, uv cache clean ruff will clear the cache for the
+ ruff package.--refresh to any command (e.g.,
+ uv sync --refresh or uv pip install --refresh ...).--refresh-package to any
+ command (e.g., uv sync --refresh-package ruff or uv pip install --refresh-package ruff ...).--reinstall to any installation command
+ (e.g., uv sync --reinstall or uv pip install --reinstall ...). (Consider running
+ uv cache clean <package-name> first, to ensure that the cache is cleared prior to
+ reinstallation.)As a special case, uv will always rebuild and reinstall any local directory dependencies passed
+explicitly on the command-line (e.g., uv pip install .).
By default, uv will only rebuild and reinstall local directory dependencies (e.g., editables) if
+the pyproject.toml, setup.py, or setup.cfg file in the directory root has changed, or if a
+src directory is added or removed. This is a heuristic and, in some cases, may lead to fewer
+re-installs than desired.
To incorporate additional information into the cache key for a given package, you can add cache key
+entries under tool.uv.cache-keys,
+which covers both file paths and Git commit hashes. Setting
+tool.uv.cache-keys will replace
+defaults, so any necessary files (like pyproject.toml) should still be included in the
+user-defined cache keys.
For example, if a project specifies dependencies in pyproject.toml but uses
+setuptools-scm to manage its version, and should thus
+be rebuilt whenever the commit hash or dependencies change, you can add the following to the
+project's pyproject.toml:
If your dynamic metadata incorporates information from the set of Git tags, you can expand the cache +key to include the tags:
+[tool.uv]
+cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true } }]
+Similarly, if a project reads from a requirements.txt to populate its dependencies, you can add
+the following to the project's pyproject.toml:
[tool.uv]
+cache-keys = [{ file = "pyproject.toml" }, { file = "requirements.txt" }]
+Globs are supported for file keys, following the syntax of the
+glob crate. For example, to invalidate the
+cache whenever a .toml file in the project directory or any of its subdirectories is modified, use
+the following:
Note
+The use of globs can be expensive, as uv may need to walk the filesystem to determine whether any files have changed. +This may, in turn, requiring traversal of large or deeply nested directories.
+Similarly, if a project relies on an environment variable, you can add the following to the
+project's pyproject.toml to invalidate the cache whenever the environment variable changes:
Finally, to invalidate a project whenever a specific directory (like src) is created or removed,
+add the following to the project's pyproject.toml:
Note that the dir key will only track changes to the directory itself, and not arbitrary changes
+within the directory.
As an escape hatch, if a project uses dynamic metadata that isn't covered by tool.uv.cache-keys,
+you can instruct uv to always rebuild and reinstall it by adding the project to the
+tool.uv.reinstall-package list:
This will force uv to rebuild and reinstall my-package on every run, regardless of whether the
+package's pyproject.toml, setup.py, or setup.cfg file has changed.
It's safe to run multiple uv commands concurrently, even against the same virtual environment. uv's +cache is designed to be thread-safe and append-only, and thus robust to multiple concurrent readers +and writers. uv applies a file-based lock to the target virtual environment when installing, to +avoid concurrent modifications across processes.
+Note that it's not safe to modify the uv cache (e.g., uv cache clean) while other uv commands
+are running, and never safe to modify the cache directly (e.g., by removing a file or directory).
uv provides a few different mechanisms for removing entries from the cache:
+uv cache clean removes all cache entries from the cache directory, clearing it out entirely.uv cache clean ruff removes all cache entries for the ruff package, useful for invalidating
+ the cache for a single or finite set of packages.uv cache prune removes all unused cache entries. For example, the cache directory may contain
+ entries created in previous uv versions that are no longer necessary and can be safely removed.
+ uv cache prune is safe to run periodically, to keep the cache directory clean.It's common to cache package installation artifacts in continuous integration environments (like +GitHub Actions or GitLab CI) to speed up subsequent runs.
+By default, uv caches both the wheels that it builds from source and the pre-built wheels that it +downloads directly, to enable high-performance package installation.
+However, in continuous integration environments, persisting pre-built wheels may be undesirable. +With uv, it turns out that it's often faster to omit pre-built wheels from the cache (and instead +re-download them from the registry on each run). On the other hand, caching wheels that are built +from source tends to be worthwhile, since the wheel building process can be expensive, especially +for extension modules.
+To support this caching strategy, uv provides a uv cache prune --ci command, which removes all
+pre-built wheels and unzipped source distributions from the cache, but retains any wheels that were
+built from source. We recommend running uv cache prune --ci at the end of your continuous
+integration job to ensure maximum cache efficiency. For an example, see the
+GitHub integration guide.
uv determines the cache directory according to, in order:
+--no-cache was requested.--cache-dir, UV_CACHE_DIR, or
+ tool.uv.cache-dir.$XDG_CACHE_HOME/uv or $HOME/.cache/uv on Unix and
+ %LOCALAPPDATA%\uv\cache on WindowsNote
+uv always requires a cache directory. When --no-cache is requested, uv will still use
+a temporary cache for sharing data within that single invocation.
In most cases, --refresh should be used instead of --no-cache — as it will update the cache
+for subsequent operations but not read from the cache.
It is important for performance for the cache directory to be located on the same file system as the +Python environment uv is operating on. Otherwise, uv will not be able to link files from the cache +into the environment and will instead need to fallback to slow copy operations.
+The uv cache is composed of a number of buckets (e.g., a bucket for wheels, a bucket for source +distributions, a bucket for Git repositories, and so on). Each bucket is versioned, such that if a +release contains a breaking change to the cache format, uv will not attempt to read from or write to +an incompatible cache bucket.
+For example, uv 0.4.13 included a breaking change to the core metadata bucket. As such, the bucket +version was increased from v12 to v13. Within a cache version, changes are guaranteed to be both +forwards- and backwards-compatible.
+Since changes in the cache format are accompanied by changes in the cache version, multiple versions +of uv can safely read and write to the same cache directory. However, if the cache version changed +between a given pair of uv releases, then those releases may not be able to share the same +underlying cache entries.
+For example, it's safe to use a single shared cache for uv 0.4.12 and uv 0.4.13, though the cache +itself may contain duplicate entries in the core metadata bucket due to the change in cache version.
+ + + + + + + + + + + + + + + + + +uv supports persistent configuration files at both the project- and user-level.
+Specifically, uv will search for a pyproject.toml or uv.toml file in the current directory, or
+in the nearest parent directory.
Note
+For tool commands, which operate at the user level, local configuration
+files will be ignored. Instead, uv will exclusively read from user-level configuration
+(e.g., ~/.config/uv/uv.toml) and system-level configuration (e.g., /etc/uv/uv.toml).
In workspaces, uv will begin its search at the workspace root, ignoring any configuration defined in +workspace members. Since the workspace is locked as a single unit, configuration is shared across +all members.
+If a pyproject.toml file is found, uv will read configuration from the [tool.uv] table. For
+example, to set a persistent index URL, add the following to a pyproject.toml:
(If there is no such table, the pyproject.toml file will be ignored, and uv will continue
+searching in the directory hierarchy.)
uv will also search for uv.toml files, which follow an identical structure, but omit the
+[tool.uv] prefix. For example:
Note
+uv.toml files take precedence over pyproject.toml files, so if both uv.toml and
+pyproject.toml files are present in a directory, configuration will be read from uv.toml, and
+[tool.uv] section in the accompanying pyproject.toml will be ignored.
uv will also discover user-level configuration at ~/.config/uv/uv.toml (or
+$XDG_CONFIG_HOME/uv/uv.toml) on macOS and Linux, or %APPDATA%\uv\uv.toml on Windows; and
+system-level configuration at /etc/uv/uv.toml (or $XDG_CONFIG_DIRS/uv/uv.toml) on macOS and
+Linux, or %SYSTEMDRIVE%\ProgramData\uv\uv.toml on Windows.
User-and system-level configuration must use the uv.toml format, rather than the pyproject.toml
+format, as a pyproject.toml is intended to define a Python project.
If project-, user-, and system-level configuration files are found, the settings will be merged,
+with project-level configuration taking precedence over the user-level configuration, and user-level
+configuration taking precedence over the system-level configuration. (If multiple system-level
+configuration files are found, e.g., at both /etc/uv/uv.toml and $XDG_CONFIG_DIRS/uv/uv.toml,
+only the first-discovered file will be used, with XDG taking priority.)
For example, if a string, number, or boolean is present in both the project- and user-level +configuration tables, the project-level value will be used, and the user-level value will be +ignored. If an array is present in both tables, the arrays will be concatenated, with the +project-level settings appearing earlier in the merged array.
+Settings provided via environment variables take precedence over persistent configuration, and +settings provided via the command line take precedence over both.
+uv accepts a --no-config command-line argument which, when provided, disables the discovery of any
+persistent configuration.
uv also accepts a --config-file command-line argument, which accepts a path to a uv.toml to use
+as the configuration file. When provided, this file will be used in place of any discovered
+configuration files (e.g., user-level configuration will be ignored).
See the settings reference for an enumeration of the available settings.
+.envuv run can load environment variables from dotenv files (e.g., .env, .env.local,
+.env.development), powered by the dotenvy crate.
To load a .env file from a dedicated location, set the UV_ENV_FILE environment variable, or pass
+the --env-file flag to uv run.
For example, to load environment variables from a .env file in the current working directory:
$ echo "MY_VAR='Hello, world!'" > .env
+$ uv run --env-file .env -- python -c 'import os; print(os.getenv("MY_VAR"))'
+Hello, world!
+The --env-file flag can be provided multiple times, with subsequent files overriding values
+defined in previous files. To provide multiple files via the UV_ENV_FILE environment variable,
+separate the paths with a space (e.g., UV_ENV_FILE="/path/to/file1 /path/to/file2").
To disable dotenv loading (e.g., to override UV_ENV_FILE or the --env-file command-line
+argument), set the UV_NO_ENV_FILE environment variable to 1, or pass the--no-env-file flag to
+uv run.
If the same variable is defined in the environment and in a .env file, the value from the
+environment will take precedence.
A dedicated [tool.uv.pip] section is provided for configuring
+just the uv pip command line interface. Settings in this section will not apply to uv commands
+outside the uv pip namespace. However, many of the settings in this section have corollaries in
+the top-level namespace which do apply to the uv pip interface unless they are overridden by a
+value in the uv.pip section.
The uv.pip settings are designed to adhere closely to pip's interface and are declared separately
+to retain compatibility while allowing the global settings to use alternate designs (e.g.,
+--no-build).
As an example, setting the index-url under [tool.uv.pip], as in the following pyproject.toml,
+would only affect the uv pip subcommands (e.g., uv pip install, but not uv sync, uv lock, or
+uv run):
Read the concept documents to learn more about uv's features:
+Looking for a quick introduction to features? See the guides instead.
+ + + + + + + + + + + + + + + + + +By default, uv uses the Python Package Index (PyPI) for dependency resolution
+and package installation. However, uv can be configured to use other package indexes, including
+private indexes, via the [[tool.uv.index]] configuration option (and --index, the analogous
+command-line option).
To include an additional index when resolving dependencies, add a [[tool.uv.index]] entry to your
+pyproject.toml:
[[tool.uv.index]]
+# Optional name for the index.
+name = "pytorch"
+# Required URL for the index.
+url = "https://download.pytorch.org/whl/cpu"
+Indexes are prioritized in the order in which they’re defined, such that the first index listed in +the configuration file is the first index consulted when resolving dependencies, with indexes +provided via the command line taking precedence over those in the configuration file.
+By default, uv includes the Python Package Index (PyPI) as the "default" index, i.e., the index used
+when a package is not found on any other index. To exclude PyPI from the list of indexes, set
+default = true on another index entry (or use the --default-index command-line option):
The default index is always treated as lowest priority, regardless of its position in the list of +indexes.
+Index names may only contain alphanumeric characters, dashes, underscores, and periods, and must be +valid ASCII.
+When providing an index on the command line (with --index or --default-index) or through an
+environment variable (UV_INDEX or UV_DEFAULT_INDEX), names are optional but can be included
+using the <name>=<url> syntax, as in:
# On the command line.
+$ uv lock --index pytorch=https://download.pytorch.org/whl/cpu
+# Via an environment variable.
+$ UV_INDEX=pytorch=https://download.pytorch.org/whl/cpu uv lock
+A package can be pinned to a specific index by specifying the index in its tool.uv.sources entry.
+For example, to ensure that torch is always installed from the pytorch index, add the
+following to your pyproject.toml:
[tool.uv.sources]
+torch = { index = "pytorch" }
+
+[[tool.uv.index]]
+name = "pytorch"
+url = "https://download.pytorch.org/whl/cpu"
+Similarly, to pull from a different index based on the platform, you can provide a list of sources +disambiguated by environment markers:
+[project]
+dependencies = ["torch"]
+
+[tool.uv.sources]
+torch = [
+ { index = "pytorch-cu118", marker = "sys_platform == 'darwin'"},
+ { index = "pytorch-cu124", marker = "sys_platform != 'darwin'"},
+]
+
+[[tool.uv.index]]
+name = "pytorch-cu118"
+url = "https://download.pytorch.org/whl/cu118"
+
+[[tool.uv.index]]
+name = "pytorch-cu124"
+url = "https://download.pytorch.org/whl/cu124"
+An index can be marked as explicit = true to prevent packages from being installed from that index
+unless explicitly pinned to it. For example, to ensure that torch is installed from the pytorch
+index, but all other packages are installed from PyPI, add the following to your pyproject.toml:
[tool.uv.sources]
+torch = { index = "pytorch" }
+
+[[tool.uv.index]]
+name = "pytorch"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+Named indexes referenced via tool.uv.sources must be defined within the project's pyproject.toml
+file; indexes provided via the command-line, environment variables, or user-level configuration will
+not be recognized.
If an index is marked as both default = true and explicit = true, it will be treated as an
+explicit index (i.e., only usable via tool.uv.sources) while also removing PyPI as the default
+index.
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).
For example, if an internal index is specified via [[tool.uv.index]], uv's behavior is such that
+if a package exists on that internal index, it will always be installed from that internal index,
+and never from PyPI. The intent is to prevent "dependency confusion" attacks, in which an attacker
+publishes a malicious package on PyPI with the same name as an internal package, thus causing the
+malicious package to be installed instead of the internal package. See, for example,
+the torchtriton attack from
+December 2022.
To opt in to alternate index behaviors, use the--index-strategy command-line option, or the
+UV_INDEX_STRATEGY environment variable, which supports the following values:
first-index (default): Search for each package across all indexes, limiting the candidate
+ versions to those present in the first index that contains the package.unsafe-first-match: Search for each package across all indexes, but prefer the first index with
+ a compatible version, even if newer versions are available on other indexes.unsafe-best-match: Search for each package across all indexes, and select the best version from
+ the combined set of candidate versions.While unsafe-best-match is the closest to pip's behavior, it exposes users to the risk of
+"dependency confusion" attacks.
Most private package indexes require authentication to access packages, typically via a username and +password (or access token).
+Tip
+See the alternative index guide for details on +authenticating with specific private index providers, e.g., from AWS, Azure, or GCP.
+Credentials can be provided directly via environment variables or by embedding them in the URL.
+For example, given an index named internal-proxy that requires a username (public) and password
+(koala), define the index (without credentials) in your pyproject.toml:
From there, you can set the UV_INDEX_INTERNAL_PROXY_USERNAME and
+UV_INDEX_INTERNAL_PROXY_PASSWORD environment variables, where INTERNAL_PROXY is the uppercase
+version of the index name, with non-alphanumeric characters replaced by underscores:
By providing credentials via environment variables, you can avoid storing sensitive information in
+the plaintext pyproject.toml file.
Alternatively, credentials can be embedded directly in the index definition:
+ +For security purposes, credentials are never stored in the uv.lock file; as such, uv must have
+access to the authenticated URL at installation time.
In addition to providing credentials directly, uv supports discovery of credentials from netrc and +keyring. See the HTTP authentication documentation for details on +setting up specific credential providers.
+By default, uv will attempt an unauthenticated request before querying providers. If the request +fails, uv will search for credentials. If credentials are found, an authenticated request will be +attempted.
+Note
+If a username is set, uv will search for credentials before making an unauthenticated request.
+Some indexes (e.g., GitLab) will forward unauthenticated requests to a public index, like PyPI —
+which means that uv will not search for credentials. This behavior can be changed per-index, using
+the authenticate setting. For example, to always search for credentials:
When authenticate is set to always, uv will eagerly search for credentials and error if
+credentials cannot be found.
When using the first-index strategy, uv will stop searching
+across indexes if an HTTP 401 Unauthorized or HTTP 403 Forbidden status code is encountered. The one
+exception is that uv will ignore 403s when searching the pytorch index (since this index returns a
+403 when a package is not present).
To configure which error codes are ignored for an index, use the ignored-error-codes setting. For
+example, to ignore 403s (but not 401s) for a private index:
[[tool.uv.index]]
+name = "private-index"
+url = "https://private-index.com/simple"
+authenticate = "always"
+ignore-error-codes = [403]
+uv will always continue searching across indexes when it encounters a 404 Not Found. This cannot
+be overridden.
To prevent leaking credentials, authentication can be disabled for an index:
+ +When authenticate is set to never, uv will never search for credentials for the given index and
+will error if credentials are provided directly.
By default, uv will respect the cache control headers provided by the index. For example, PyPI
+serves package metadata with a max-age=600 header, thereby allowing uv to cache package metadata
+for 10 minutes; and wheels and source distributions with a max-age=365000000, immutable header,
+thereby allowing uv to cache artifacts indefinitely.
To override the cache control headers for an index, use the cache-control setting:
[[tool.uv.index]]
+name = "example"
+url = "https://example.com/simple"
+cache-control = { api = "max-age=600", files = "max-age=365000000, immutable" }
+The cache-control setting accepts an object with two optional keys:
api: Controls caching for Simple API requests (package metadata).files: Controls caching for artifact downloads (wheels and source distributions).The values for these keys are strings that follow the
+HTTP Cache-Control
+syntax. For example, to force uv to always revalidate package metadata, set api = "no-cache":
[[tool.uv.index]]
+name = "example"
+url = "https://example.com/simple"
+cache-control = { api = "no-cache" }
+This setting is most commonly used to override the default cache control headers for private indexes
+that otherwise disable caching, often unintentionally. We typically recommend following PyPI's
+approach to caching headers, i.e., setting api = "max-age=600" and
+files = "max-age=365000000, immutable".
By default, [[tool.uv.index]] entries are assumed to be PyPI-style registries that implement the
+PEP 503 Simple Repository API. However, uv also supports "flat"
+indexes, which are local directories or HTML pages that contain flat lists of wheels and source
+distributions. In pip, such indexes are specified using the --find-links option.
To define a flat index in your pyproject.toml, use the format = "flat" option:
Flat indexes support the same feature set as Simple Repository API indexes (e.g.,
+explicit = true); you can also pin a package to a flat index using tool.uv.sources.
--index-url and --extra-index-urlIn addition to the [[tool.uv.index]] configuration option, uv supports pip-style --index-url and
+--extra-index-url command-line options for compatibility, where --index-url defines the default
+index and --extra-index-url defines additional indexes.
These options can be used in conjunction with the [[tool.uv.index]] configuration option, and
+follow the same prioritization rules:
--index-url argument, the recommended --default-index argument, or a [[tool.uv.index]] entry
+ with default = true.--extra-index-url argument, the recommended --index argument, or [[tool.uv.index]] entries.In effect, --index-url and --extra-index-url can be thought of as unnamed [[tool.uv.index]]
+entries, with default = true enabled for the former. In that context, --index-url maps to
+--default-index, and --extra-index-url maps to --index.
uv includes opt-in preview features to provide an opportunity for community feedback and increase +confidence that changes are a net-benefit before enabling them for everyone.
+To enable all preview features, use the --preview flag:
Or, set the UV_PREVIEW environment variable:
To enable specific preview features, use the --preview-features flag:
The --preview-features flag can be repeated to enable multiple features:
Or, features can be provided in a comma separated list:
+ +The UV_PREVIEW_FEATURES environment variable can be used similarly, e.g.:
For backwards compatibility, enabling preview features that do not exist will warn, but not error.
+Often, preview features can be used without changing any preview settings if the behavior change is
+gated by some sort of user interaction, For example, while pylock.toml support is in preview, you
+can use uv pip install with a pylock.toml file without additional configuration because
+specifying the pylock.toml file indicates you want to use the feature. However, a warning will be
+displayed that the feature is in preview. The preview feature can be enabled to silence the warning.
Other preview features change behavior without changes to your use of uv. For example, when the
+python-upgrade feature is enabled, the default behavior of uv python install changes to allow uv
+to upgrade Python versions transparently. This feature requires enabling the preview flag for proper
+usage.
The following preview features are available:
+add-bounds: Allows configuring the
+ default bounds for uv add invocations.json-output: Allows --output-format json for various uv commands.package-conflicts: Allows defining workspace conflicts at the package level.pylock: Allows installing from pylock.toml files.python-install-default: Allows
+ installing python and python3 executables.python-upgrade: Allows
+ transparent Python version upgrades.format: Allows using uv format.native-auth: Enables storage of credentials in a
+ system-native location.The --no-preview option can be used to disable preview features.
To distribute your project to others (e.g., to upload it to an index like PyPI), you'll need to +build it into a distributable format.
+Python projects are typically distributed as both source distributions (sdists) and binary
+distributions (wheels). The former is typically a .tar.gz or .zip file containing the project's
+source code along with some additional metadata, while the latter is a .whl file containing
+pre-built artifacts that can be installed directly.
Important
+When using uv build, uv acts as a build frontend
+and only determines the Python version to use and invokes the build backend. The details of
+the builds, such as the included files and the distribution filenames, are determined by the build
+backend, as defined in [build-system]. Information about build
+configuration can be found in the respective tool's documentation.
uv builduv build can be used to build both source distributions and binary distributions for your project.
+By default, uv build will build the project in the current directory, and place the built
+artifacts in a dist/ subdirectory:
You can build the project in a different directory by providing a path to uv build, e.g.,
+uv build path/to/project.
uv build will first build a source distribution, and then build a binary distribution (wheel) from
+that source distribution.
You can limit uv build to building a source distribution with uv build --sdist, a binary
+distribution with uv build --wheel, or build both distributions from source with
+uv build --sdist --wheel.
uv build accepts --build-constraint, which can be used to constrain the versions of any build
+requirements during the build process. When coupled with --require-hashes, uv will enforce that
+the requirement used to build the project match specific, known hashes, for reproducibility.
For example, given the following constraints.txt:
Running the following would build the project with the specified version of setuptools, and verify
+that the downloaded setuptools distribution matches the specified hash:
Projects may declare the Python versions supported by the project in the project.requires-python
+field of the pyproject.toml.
It is recommended to set a requires-python value:
The Python version requirement determines the Python syntax that is allowed in the project and +affects selection of dependency versions (they must support the same Python version range).
+Entry points are +the official term for an installed package to advertise interfaces. These include:
+ +Important
+Using the entry point tables requires a build system to be defined.
+Projects may define command line interfaces (CLIs) for the project in the [project.scripts] table
+of the pyproject.toml.
For example, to declare a command called hello that invokes the hello function in the example
+module:
Then, the command can be run from a console:
+ +Projects may define graphical user interfaces (GUIs) for the project in the [project.gui-scripts]
+table of the pyproject.toml.
Important
+These are only different from command-line interfaces on Windows, where +they are wrapped by a GUI executable so they can be started without a console. On other platforms, +they behave the same.
+For example, to declare a command called hello that invokes the app function in the example
+module:
Projects may define entry points for plugin discovery in the
+[project.entry-points]
+table of the pyproject.toml.
For example, to register the example-plugin-a package as a plugin for example:
Then, in example, plugins would be loaded with:
from importlib.metadata import entry_points
+
+for plugin in entry_points(group='example.plugins'):
+ plugin.load()
+Note
+The group key can be an arbitrary value, it does not need to include the package name or
+"plugins". However, it is recommended to namespace the key by the package name to avoid
+collisions with other packages.
A build system determines how the project should be packaged and installed. Projects may declare and
+configure a build system in the [build-system] table of the pyproject.toml.
uv uses the presence of a build system to determine if a project contains a package that should be +installed in the project virtual environment. If a build system is not defined, uv will not attempt +to build or install the project itself, just its dependencies. If a build system is defined, uv will +build and install the project into the project environment.
+The --build-backend option can be provided to uv init to create a packaged project with an
+appropriate layout. The --package option can be provided to uv init to create a packaged project
+with the default build system.
Note
+While uv will not build and install the current project without a build system definition,
+the presence of a [build-system] table is not required in other packages. For legacy reasons,
+if a build system is not defined, then setuptools.build_meta:__legacy__ is used to build the
+package. Packages you depend on may not explicitly declare their build system but are still
+installable. Similarly, if you add a dependency on a local project
+or install it with uv pip, uv will attempt to build and install it regardless of the presence
+of a [build-system] table.
Build systems are used to power the following features:
+To configure these features, refer to the documentation of your chosen build system.
+As discussed in build systems, a Python project must be built to be installed. +This process is generally referred to as "packaging".
+You probably need a package if you want to:
+src and test layoutYou probably do not need a package if you are:
+While uv usually uses the declaration of a build system to determine if a project
+should be packaged, uv also allows overriding this behavior with the
+tool.uv.package setting.
Setting tool.uv.package = true will force a project to be built and installed into the project
+environment. If no build system is defined, uv will use the setuptools legacy backend.
Setting tool.uv.package = false will force a project package not to be built and installed into
+the project environment. uv will ignore a declared build system when interacting with the project;
+however, uv will still respect explicit attempts to build the project such as invoking uv build.
The UV_PROJECT_ENVIRONMENT environment variable can be used to configure the project virtual
+environment path (.venv by default).
If a relative path is provided, it will be resolved relative to the workspace root. If an absolute +path is provided, it will be used as-is, i.e., a child directory will not be created for the +environment. If an environment is not present at the provided path, uv will create it.
+This option can be used to write to the system Python environment, though it is not recommended.
+uv sync will remove extraneous packages from the environment by default and, as such, may leave
+the system in a broken state.
To target the system environment, set UV_PROJECT_ENVIRONMENT to the prefix of the Python
+installation. For example, on Debian-based systems, this is usually /usr/local:
To target this environment, you'd export UV_PROJECT_ENVIRONMENT=/usr/local.
Important
+If an absolute path is provided and the setting is used across multiple projects, the +environment will be overwritten by invocations in each project. This setting is only recommended +for use for a single project in CI or Docker images.
+Note
+By default, uv does not read the VIRTUAL_ENV environment variable during project operations.
+A warning will be displayed if VIRTUAL_ENV is set to a different path than the project's
+environment. The --active flag can be used to opt-in to respecting VIRTUAL_ENV. The
+--no-active flag can be used to silence the warning.
By default, uv builds all packages in isolated virtual environments alongside their declared build +dependencies, as per PEP 517.
+Some packages are incompatible with this approach to build isolation, be it intentionally or +unintentionally.
+For example, packages like flash-attn and
+deepspeed need to build against the same version of PyTorch
+that is installed in the project environment; by building them in an isolated environment, they may
+inadvertently build against a different version of PyTorch, leading to runtime errors.
In other cases, packages may accidentally omit necessary dependencies in their declared build
+dependency list. For example, cchardet requires cython to
+be installed in the project environment prior to installing cchardet, but does not declare it as a
+build dependency.
To address these issues, uv supports two separate approaches to modifying the build isolation +behavior:
+Augmenting the list of build dependencies: This allows you to install a package in an
+ isolated environment, but with additional build dependencies that are not declared by the package
+ itself via the extra-build-dependencies
+ setting. For packages like flash-attn, you can even enforce that those build dependencies (like
+ torch) match the version of the package that is or will be installed in the project
+ environment.
Disabling build isolation for specific packages: This allows you to install a package without + building it in an isolated environment.
+When possible, we recommend augmenting the build dependencies rather than disabling build isolation +entirely, as the latter approach requires that the build dependencies are installed in the project +environment prior to installing the package itself, which can lead to more complex installation +steps, the inclusion of extraneous packages in the project environment, and difficulty in +reproducing the project environment in other contexts.
+To augment the list of build dependencies for a specific package, add it to the
+extra-build-dependencies list in your
+pyproject.toml.
For example, to build cchardet with cython as an additional build dependency, include the
+following in your pyproject.toml:
[project]
+name = "project"
+version = "0.1.0"
+description = "..."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["cchardet"]
+
+[tool.uv.extra-build-dependencies]
+cchardet = ["cython"]
+To ensure that a build dependency matches the version of the package that is or will be installed in
+the project environment, set match-runtime = true in the extra-build-dependencies table. For
+example, to build deepspeed with torch as an additional build dependency, include the following
+in your pyproject.toml:
[project]
+name = "project"
+version = "0.1.0"
+description = "..."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["deepspeed", "torch"]
+
+[tool.uv.extra-build-dependencies]
+deepspeed = [{ requirement = "torch", match-runtime = true }]
+This will ensure that deepspeed is built with the same version of torch that is installed in the
+project environment.
Similarly, to build flash-attn with torch as an additional build dependency, include the
+following in your pyproject.toml:
[project]
+name = "project"
+version = "0.1.0"
+description = "..."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["flash-attn", "torch"]
+
+[tool.uv.extra-build-dependencies]
+flash-attn = [{ requirement = "torch", match-runtime = true }]
+
+[tool.uv.extra-build-variables]
+flash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = "TRUE" }
+Note
+The FLASH_ATTENTION_SKIP_CUDA_BUILD environment variable ensures that flash-attn is installed
+from a compatible, pre-built wheel, rather than attempting to build it from source, which requires
+access to the CUDA development toolkit. If the CUDA toolkit is not available, the environment variable
+can be omitted, and flash-attn will be installed from a pre-built wheel if one is available for the
+current platform, Python version, and PyTorch version.
Similarly, deep_gemm follows the same pattern:
[project]
+name = "project"
+version = "0.1.0"
+description = "..."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["deep_gemm", "torch"]
+
+[tool.uv.sources]
+deep_gemm = { git = "https://github.com/deepseek-ai/DeepGEMM" }
+
+[tool.uv.extra-build-dependencies]
+deep_gemm = [{ requirement = "torch", match-runtime = true }]
+The use of extra-build-dependencies and extra-build-variables are tracked in the uv cache, such
+that changes to these settings will trigger a reinstall and rebuild of the affected packages. For
+example, in the case of flash-attn, upgrading the version of torch used in your project would
+subsequently trigger a rebuild of flash-attn with the new version of torch.
The use of match-runtime = true is only available for packages like flash-attn that declare
+static metadata. If static metadata is unavailable, uv is required to build the package during the
+dependency resolution phase; as such, uv cannot determine the version of the build dependency that
+would ultimately be installed in the project environment.
In other words, if flash-attn did not declare static metadata, uv would not be able to determine
+the version of torch that would be installed in the project environment, since it would need to
+build flash-attn prior to resolving the torch version.
As a concrete example, axolotl is a popular package that
+requires augmented build dependencies, but does not declare static metadata, as the package's
+dependencies vary based on the version of torch that is installed in the project environment. In
+this case, users should instead specify the exact version of torch that they intend to use in
+their project, and then augment the build dependencies with that version.
For example, to build axolotl against torch==2.6.0, include the following in your
+pyproject.toml:
[project]
+name = "project"
+version = "0.1.0"
+description = "..."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["axolotl[deepspeed, flash-attn]", "torch==2.6.0"]
+
+[tool.uv.extra-build-dependencies]
+axolotl = ["torch==2.6.0"]
+deepspeed = ["torch==2.6.0"]
+flash-attn = ["torch==2.6.0"]
+Similarly, older versions of flash-attn did not declare static metadata, and thus would not have
+supported match-runtime = true out of the box. Unlike axolotl, though, flash-attn did not vary
+its dependencies based on dynamic properties of the build environment. As such, users could instead
+provide the flash-attn metadata upfront via the
+dependency-metadata setting, thereby forgoing
+the need to build the package during the dependency resolution phase. For example, to provide the
+flash-attn metadata upfront:
[[tool.uv.dependency-metadata]]
+name = "flash-attn"
+version = "2.6.3"
+requires-dist = ["torch", "einops"]
+Tip
+To determine the package metadata for a package like flash-attn, navigate to the appropriate Git repository,
+or look it up on PyPI and download the package's source distribution.
+The package requirements can typically be found in the setup.py or setup.cfg file.
(If the package includes a built distribution, you can unzip it to find the METADATA file; however, the presence
+of a built distribution would negate the need to provide the metadata upfront, since it would already be available
+to uv.)
The version field in tool.uv.dependency-metadata is optional for registry-based
+dependencies (when omitted, uv will assume the metadata applies to all versions of the package),
+but required for direct URL dependencies (like Git dependencies).
Installing packages without build isolation requires that the package's build dependencies are +installed in the project environment prior to building the package itself.
+For example, historically, to install cchardet without build isolation, you would first need to
+install the cython and setuptools packages in the project environment, followed by a separate
+invocation to install cchardet without build isolation:
uv simplifies this process by allowing you to specify packages that should not be built in isolation
+via the no-build-isolation-package setting in your pyproject.toml and the
+--no-build-isolation-package flag in the command line. Further, when a package is marked for
+disabling build isolation, uv will perform a two-phase install, first installing any packages that
+support build isolation, followed by those that do not. As a result, if a project's build
+dependencies are included as project dependencies, uv will automatically install them before
+installing the package that requires build isolation to be disabled.
For example, to install cchardet without build isolation, include the following in your
+pyproject.toml:
[project]
+name = "project"
+version = "0.1.0"
+description = "..."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["cchardet", "cython", "setuptools"]
+
+[tool.uv]
+no-build-isolation-package = ["cchardet"]
+When running uv sync, uv will first install cython and setuptools in the project environment,
+followed by cchardet (without build isolation):
Similarly, to install flash-attn without build isolation, include the following in your
+pyproject.toml:
[project]
+name = "project"
+version = "0.1.0"
+description = "..."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["flash-attn", "torch"]
+
+[tool.uv]
+no-build-isolation-package = ["flash-attn"]
+When running uv sync, uv will first install torch in the project environment, followed by
+flash-attn (without build isolation). As torch is both a project dependency and a build
+dependency, the version of torch is guaranteed to be consistent between the build and runtime
+environments.
A downside of the above approach is that it requires the build dependencies to be installed in the
+project environment, which is appropriate for flash-attn (which requires torch both at
+build-time and runtime), but not for cchardet (which only requires cython at build-time).
To avoid including build dependencies in the project environment, uv supports a two-step +installation process that allows you to separate the build dependencies from the packages that +require them.
+For example, the build dependencies for cchardet can be isolated to an optional build group, as
+in:
[project]
+name = "project"
+version = "0.1.0"
+description = "..."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["cchardet"]
+
+[project.optional-dependencies]
+build = ["setuptools", "cython"]
+
+[tool.uv]
+no-build-isolation-package = ["cchardet"]
+Given the above, a user would first sync with the build optional group, and then without it to
+remove the build dependencies:
$ uv sync --extra build
+ + cchardet==2.1.7
+ + cython==3.1.3
+ + setuptools==80.9.0
+$ uv sync
+ - cython==3.1.3
+ - setuptools==80.9.0
+Some packages, like cchardet, only require build dependencies for the installation phase of
+uv sync. Others require their build dependencies to be present even just to resolve the project's
+dependencies during the resolution phase.
In such cases, the build dependencies can be installed prior to running any uv lock or uv sync
+commands, using the lower lower-level uv pip API. For example, given:
[project]
+name = "project"
+version = "0.1.0"
+description = "..."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["flash-attn"]
+
+[tool.uv]
+no-build-isolation-package = ["flash-attn"]
+You could run the following sequence of commands to sync flash-attn:
Alternatively, users can instead provide the flash-attn metadata upfront via the
+dependency-metadata setting, thereby forgoing
+the need to build the package during the dependency resolution phase. For example, to provide the
+flash-attn metadata upfront:
[[tool.uv.dependency-metadata]]
+name = "flash-attn"
+version = "2.6.3"
+requires-dist = ["torch", "einops"]
+By default, the project will be installed in editable mode, such that changes to the source code are
+immediately reflected in the environment. uv sync and uv run both accept a --no-editable flag,
+which instructs uv to install the project in non-editable mode. --no-editable is intended for
+deployment use-cases, such as building a Docker container, in which the project should be included
+in the deployed environment without a dependency on the originating source code.
uv resolves all project dependencies together, including optional dependencies ("extras") and +dependency groups. If dependencies declared in one section are not compatible with those in another +section, uv will fail to resolve the requirements of the project with an error.
+uv supports explicit declaration of conflicting dependency groups. For example, to declare that the
+optional-dependency groups extra1 and extra2 are incompatible:
[tool.uv]
+conflicts = [
+ [
+ { extra = "extra1" },
+ { extra = "extra2" },
+ ],
+]
+Or, to declare the development dependency groups group1 and group2 incompatible:
[tool.uv]
+conflicts = [
+ [
+ { group = "group1" },
+ { group = "group2" },
+ ],
+]
+See the resolution documentation for more.
+If your project supports a more limited set of platforms or Python versions, you can constrain the
+set of solved platforms via the environments setting, which accepts a list of PEP 508 environment
+markers. For example, to constrain the lockfile to macOS and Linux, and exclude Windows:
[tool.uv]
+environments = [
+ "sys_platform == 'darwin'",
+ "sys_platform == 'linux'",
+]
+See the resolution documentation for more.
+If your project must support a specific platform or Python version, you can mark that platform as
+required via the required-environments setting. For example, to require that the project supports
+Intel macOS:
[tool.uv]
+required-environments = [
+ "sys_platform == 'darwin' and platform_machine == 'x86_64'",
+]
+The required-environments setting is only relevant for packages that do not publish a source
+distribution (like PyTorch), as such packages can only be installed on environments covered by the
+set of pre-built binary distributions (wheels) published by that package.
See the resolution documentation for more.
+ + + + + + + + + + + + + + + + + +Dependencies of the project are defined in several fields:
+project.dependencies: Published dependencies.project.optional-dependencies: Published optional dependencies, or
+ "extras".dependency-groups: Local dependencies for development.tool.uv.sources: Alternative sources for dependencies during development.Note
+The project.dependencies and project.optional-dependencies fields can be used even if
+project isn't going to be published. dependency-groups are a recently standardized feature
+and may not be supported by all tools yet.
uv supports modifying the project's dependencies with uv add and uv remove, but dependency
+metadata can also be updated by editing the pyproject.toml directly.
To add a dependency:
+ +An entry will be added in the project.dependencies field:
The --dev, --group, or
+--optional flags can be used to add dependencies to an alternative
+field.
The dependency will include a constraint, e.g., >=0.27.2, for the most recent, compatible version
+of the package. The kind of bound can be adjusted with
+--bounds, or the constraint can be provided directly:
When adding a dependency from a source other than a package registry, uv will add an entry in the
+sources field. For example, when adding httpx from GitHub:
The pyproject.toml will include a Git source entry:
[project]
+name = "example"
+version = "0.1.0"
+dependencies = [
+ "httpx",
+]
+
+[tool.uv.sources]
+httpx = { git = "https://github.com/encode/httpx" }
+If a dependency cannot be used, uv will display an error.:
+$ uv add "httpx>9999"
+ × No solution found when resolving dependencies:
+ ╰─▶ Because only httpx<=1.0.0b0 is available and your project depends on httpx>9999,
+ we can conclude that your project's requirements are unsatisfiable.
+Dependencies declared in a requirements.txt file can be added to the project with the -r option:
See the pip migration guide +for more details.
+To remove a dependency:
+ +The --dev, --group, or --optional flags can be used to remove a dependency from a specific
+table.
If a source is defined for the removed dependency, and there are no other +references to the dependency, it will also be removed.
+To change an existing dependency, e.g., to use a different constraint for httpx:
Note
+In this example, we are changing the constraints for the dependency in the pyproject.toml.
+The locked version of the dependency will only change if necessary to satisfy the new
+constraints. To force the package version to update to the latest within the constraints, use --upgrade-package <name>, e.g.:
See the lockfile documentation for more details +on upgrading packages.
+Requesting a different dependency source will update the tool.uv.sources table, e.g., to use
+httpx from a local path during development:
To ensure that a dependency is only installed on a specific platform or on specific Python versions, +use environment markers.
+For example, to install jax on Linux, but not on Windows or macOS:
The resulting pyproject.toml will then include the environment marker in the dependency
+definition:
[project]
+name = "project"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = ["jax; sys_platform == 'linux'"]
+Similarly, to include numpy on Python 3.11 and later:
See Python's environment marker +documentation for a complete enumeration of the available markers and operators.
+Tip
+Dependency sources can also be changed per-platform.
+The project.dependencies table represents the dependencies that are used when uploading to PyPI or
+building a wheel. Individual dependencies are specified using
+dependency specifiers
+syntax, and the table follows the
+PEP 621 standard.
project.dependencies defines the list of packages that are required for the project, along with
+the version constraints that should be used when installing them. Each entry includes a dependency
+name and version. An entry may include extras or environment markers for platform-specific packages.
+For example:
[project]
+name = "albatross"
+version = "0.1.0"
+dependencies = [
+ # Any version in this range
+ "tqdm >=4.66.2,<5",
+ # Exactly this version of torch
+ "torch ==2.2.2",
+ # Install transformers with the torch extra
+ "transformers[torch] >=4.39.3,<5",
+ # Only install this package on older python versions
+ # See "Environment Markers" for more information
+ "importlib_metadata >=7.1.0,<8; python_version < '3.10'",
+ "mollymawk ==0.1.0"
+]
+The tool.uv.sources table extends the standard dependency tables with alternative dependency
+sources, which are used during development.
Dependency sources add support for common patterns that are not supported by the
+project.dependencies standard, like editable installations and relative paths. For example, to
+install foo from a directory relative to the project root:
[project]
+name = "example"
+version = "0.1.0"
+dependencies = ["foo"]
+
+[tool.uv.sources]
+foo = { path = "./packages/foo" }
+The following dependency sources are supported by uv:
+Important
+Sources are only respected by uv. If another tool is used, only the definitions in the standard +project tables will be used. If another tool is being used for development, any metadata +provided in the source table will need to be re-specified in the other tool's format.
+To add Python package from a specific index, use the --index option:
uv will store the index in [[tool.uv.index]] and add a [tool.uv.sources] entry:
[project]
+dependencies = ["torch"]
+
+[tool.uv.sources]
+torch = { index = "pytorch" }
+
+[[tool.uv.index]]
+name = "pytorch"
+url = "https://download.pytorch.org/whl/cpu"
+Tip
+The above example will only work on x86-64 Linux, due to the specifics of the PyTorch index. +See the PyTorch guide for more information about setting +up PyTorch.
+Using an index source pins a package to the given index — it will not be downloaded from other
+indexes.
When defining an index, an explicit flag can be included to indicate that the index should only
+be used for packages that explicitly specify it in tool.uv.sources. If explicit is not set,
+other packages may be resolved from the index, if not found elsewhere.
[[tool.uv.index]]
+name = "pytorch"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+To add a Git dependency source, prefix a Git-compatible URL with git+.
For example:
+$ # Install over HTTP(S).
+$ uv add git+https://github.com/encode/httpx
+
+$ # Install over SSH.
+$ uv add git+ssh://git@github.com/encode/httpx
+[project]
+dependencies = ["httpx"]
+
+[tool.uv.sources]
+httpx = { git = "https://github.com/encode/httpx" }
+Specific Git references can be requested, e.g., a tag:
+ +[project]
+dependencies = ["httpx"]
+
+[tool.uv.sources]
+httpx = { git = "https://github.com/encode/httpx", tag = "0.27.0" }
+Or, a branch:
+ +[project]
+dependencies = ["httpx"]
+
+[tool.uv.sources]
+httpx = { git = "https://github.com/encode/httpx", branch = "main" }
+Or, a revision (commit):
+ +[project]
+dependencies = ["httpx"]
+
+[tool.uv.sources]
+httpx = { git = "https://github.com/encode/httpx", rev = "326b9431c761e1ef1e00b9f760d1f654c8db48c6" }
+A subdirectory may be specified if the package isn't in the repository root:
[project]
+dependencies = ["langchain"]
+
+[tool.uv.sources]
+langchain = { git = "https://github.com/langchain-ai/langchain", subdirectory = "libs/langchain" }
+To add a URL source, provide a https:// URL to either a wheel (ending in .whl) or a source
+distribution (typically ending in .tar.gz or .zip; see
+here for all supported formats).
For example:
+$ uv add "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz"
+Will result in a pyproject.toml with:
[project]
+dependencies = ["httpx"]
+
+[tool.uv.sources]
+httpx = { url = "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz" }
+URL dependencies can also be manually added or edited in the pyproject.toml with the
+{ url = <url> } syntax. A subdirectory may be specified if the source distribution isn't in the
+archive root.
To add a path source, provide the path of a wheel (ending in .whl), a source distribution
+(typically ending in .tar.gz or .zip; see
+here for all supported formats), or a directory
+containing a pyproject.toml.
For example:
+ +Will result in a pyproject.toml with:
[project]
+dependencies = ["foo"]
+
+[tool.uv.sources]
+foo = { path = "/example/foo-0.1.0-py3-none-any.whl" }
+The path may also be a relative path:
+ +Or, a path to a project directory:
+ +Important
+When using a directory as a path dependency, uv will attempt to build and install the target as +a package by default. See the virtual dependency documentation for +details.
+An editable installation is not used for path dependencies by default. An +editable installation may be requested for project directories:
+ +Which will result in a pyproject.toml with:
[project]
+dependencies = ["bar"]
+
+[tool.uv.sources]
+bar = { path = "../projects/bar", editable = true }
+Tip
+For multiple packages in the same repository, workspaces may be a better +fit.
+To declare a dependency on a workspace member, add the member name with { workspace = true }. All
+workspace members must be explicitly stated. Workspace members are always
+editable . See the workspace documentation for more
+details on workspaces.
[project]
+dependencies = ["foo==0.1.0"]
+
+[tool.uv.sources]
+foo = { workspace = true }
+
+[tool.uv.workspace]
+members = [
+ "packages/foo"
+]
+You can limit a source to a given platform or Python version by providing +dependency specifiers-compatible +environment markers for the source.
+For example, to pull httpx from GitHub, but only on macOS, use the following:
[project]
+dependencies = ["httpx"]
+
+[tool.uv.sources]
+httpx = { git = "https://github.com/encode/httpx", tag = "0.27.2", marker = "sys_platform == 'darwin'" }
+By specifying the marker on the source, uv will still include httpx on all platforms, but will
+download the source from GitHub on macOS, and fall back to PyPI on all other platforms.
You can specify multiple sources for a single dependency by providing a list of sources, +disambiguated by PEP 508-compatible +environment markers.
+For example, to pull in different httpx tags on macOS vs. Linux:
[project]
+dependencies = ["httpx"]
+
+[tool.uv.sources]
+httpx = [
+ { git = "https://github.com/encode/httpx", tag = "0.27.2", marker = "sys_platform == 'darwin'" },
+ { git = "https://github.com/encode/httpx", tag = "0.24.1", marker = "sys_platform == 'linux'" },
+]
+This strategy extends to using different indexes based on environment markers. For example, to
+install torch from different PyTorch indexes based on the platform:
[project]
+dependencies = ["torch"]
+
+[tool.uv.sources]
+torch = [
+ { index = "torch-cpu", marker = "platform_system == 'Darwin'"},
+ { index = "torch-gpu", marker = "platform_system == 'Linux'"},
+]
+
+[[tool.uv.index]]
+name = "torch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[[tool.uv.index]]
+name = "torch-gpu"
+url = "https://download.pytorch.org/whl/cu124"
+explicit = true
+To instruct uv to ignore the tool.uv.sources table (e.g., to simulate resolving with the package's
+published metadata), use the --no-sources flag:
The use of --no-sources will also prevent uv from discovering any
+workspace members that could satisfy a given dependency.
It is common for projects that are published as libraries to make some features optional to reduce
+the default dependency tree. For example, Pandas has an
+excel extra and a
+plot extra to avoid
+installation of Excel parsers and matplotlib unless someone explicitly requires them. Extras are
+requested with the package[<extra>] syntax, e.g., pandas[plot, excel].
Optional dependencies are specified in [project.optional-dependencies], a TOML table that maps
+from extra name to its dependencies, following dependency specifiers
+syntax.
Optional dependencies can have entries in tool.uv.sources the same as normal dependencies.
[project]
+name = "pandas"
+version = "1.0.0"
+
+[project.optional-dependencies]
+plot = [
+ "matplotlib>=3.6.3"
+]
+excel = [
+ "odfpy>=1.4.1",
+ "openpyxl>=3.1.0",
+ "python-calamine>=0.1.7",
+ "pyxlsb>=1.0.10",
+ "xlrd>=2.0.1",
+ "xlsxwriter>=3.0.5"
+]
+To add an optional dependency, use the --optional <extra> option:
Note
+If you have optional dependencies that conflict with one another, resolution will fail +unless you explicitly declare them as conflicting.
+Sources can also be declared as applying only to a specific optional dependency. For example, to
+pull torch from different PyTorch indexes based on an optional cpu or gpu extra:
[project]
+dependencies = []
+
+[project.optional-dependencies]
+cpu = [
+ "torch",
+]
+gpu = [
+ "torch",
+]
+
+[tool.uv.sources]
+torch = [
+ { index = "torch-cpu", extra = "cpu" },
+ { index = "torch-gpu", extra = "gpu" },
+]
+
+[[tool.uv.index]]
+name = "torch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+
+[[tool.uv.index]]
+name = "torch-gpu"
+url = "https://download.pytorch.org/whl/cu124"
+Unlike optional dependencies, development dependencies are local-only and will not be included in
+the project requirements when published to PyPI or other indexes. As such, development dependencies
+are not included in the [project] table.
Development dependencies can have entries in tool.uv.sources the same as normal dependencies.
To add a development dependency, use the --dev flag:
uv uses the [dependency-groups] table (as defined in PEP 735)
+for declaration of development dependencies. The above command will create a dev group:
The dev group is special-cased; there are --dev, --only-dev, and --no-dev flags to toggle
+inclusion or exclusion of its dependencies. See --no-default-groups to disable all default groups
+instead. Additionally, the dev group is synced by default.
Development dependencies can be divided into multiple groups, using the --group flag.
For example, to add a development dependency in the lint group:
Which results in the following [dependency-groups] definition:
Once groups are defined, the --all-groups, --no-default-groups, --group, --only-group, and
+--no-group options can be used to include or exclude their dependencies.
Tip
+The --dev, --only-dev, and --no-dev flags are equivalent to --group dev,
+--only-group dev, and --no-group dev respectively.
uv requires that all dependency groups are compatible with each other and resolves all groups +together when creating the lockfile.
+If dependencies declared in one group are not compatible with those in another group, uv will fail +to resolve the requirements of the project with an error.
+Note
+If you have dependency groups that conflict with one another, resolution will fail +unless you explicitly declare them as conflicting.
+A dependency group can include other dependency groups, e.g.:
+[dependency-groups]
+dev = [
+ {include-group = "lint"},
+ {include-group = "test"}
+]
+lint = [
+ "ruff"
+]
+test = [
+ "pytest"
+]
+An included group's dependencies cannot conflict with the other dependencies declared in a group.
+By default, uv includes the dev dependency group in the environment (e.g., during uv run or
+uv sync). The default groups to include can be changed using the tool.uv.default-groups setting.
To enable all dependencies groups by default, use "all" instead of listing group names:
Tip
+To disable this behaviour during uv run or uv sync, use --no-default-groups.
+To exclude a specific default group, use --no-group <name>.
requires-pythonBy default, dependency groups must be compatible with your project's requires-python range.
If a dependency group requires a different range of Python versions than your project, you can
+specify a requires-python for the group in [tool.uv.dependency-groups], e.g.:
[project]
+name = "example"
+version = "0.0.0"
+requires-python = ">=3.10"
+
+[dependency-groups]
+dev = ["pytest"]
+
+[tool.uv.dependency-groups]
+dev = {requires-python = ">=3.12"}
+dev-dependenciesBefore [dependency-groups] was standardized, uv used the tool.uv.dev-dependencies field to
+specify development dependencies, e.g.:
Dependencies declared in this section will be combined with the contents in the
+dependency-groups.dev. Eventually, the dev-dependencies field will be deprecated and removed.
Note
+If a tool.uv.dev-dependencies field exists, uv add --dev will use the existing section
+instead of adding a new dependency-groups.dev section.
If a project is structured as Python package, it may declare
+dependencies that are required to build the project, but not required to run it. These dependencies
+are specified in the [build-system] table under build-system.requires, following
+PEP 518.
For example, if a project uses setuptools as its build backend, it should declare setuptools as
+a build dependency:
[project]
+name = "pandas"
+version = "0.1.0"
+
+[build-system]
+requires = ["setuptools>=42"]
+build-backend = "setuptools.build_meta"
+By default, uv will respect tool.uv.sources when resolving build dependencies. For example, to use
+a local version of setuptools for building, add the source to tool.uv.sources:
[project]
+name = "pandas"
+version = "0.1.0"
+
+[build-system]
+requires = ["setuptools>=42"]
+build-backend = "setuptools.build_meta"
+
+[tool.uv.sources]
+setuptools = { path = "./packages/setuptools" }
+When publishing a package, we recommend running uv build --no-sources to ensure that the package
+builds correctly when tool.uv.sources is disabled, as is the case when using other build tools,
+like pypa/build.
A regular installation of a directory with a Python package first builds a wheel and then installs +that wheel into your virtual environment, copying all source files. When the package source files +are edited, the virtual environment will contain outdated versions.
+Editable installations solve this problem by adding a link to the project within the virtual
+environment (a .pth file), which instructs the interpreter to include the source files directly.
There are some limitations to editables (mainly: the build backend needs to support them, and native +modules aren't recompiled before import), but they are useful for development, as the virtual +environment will always use the latest changes to the package.
+uv uses editable installation for workspace packages by default.
+To add an editable dependency, use the --editable flag:
Or, to opt-out of using an editable dependency in a workspace:
+ +uv allows dependencies to be "virtual", in which the dependency itself is not installed as a +package, but its dependencies are.
+By default, dependencies are never virtual.
+A dependency with a path source can be virtual if it explicitly sets
+tool.uv.package = false. Unlike working in the dependent
+project with uv, the package will be built even if a build system is
+not declared.
To treat a dependency as virtual, set package = false on the source:
[project]
+dependencies = ["bar"]
+
+[tool.uv.sources]
+bar = { path = "../projects/bar", package = false }
+If a dependency sets tool.uv.package = false, it can be overridden by declaring package = true
+on the source:
[project]
+dependencies = ["bar"]
+
+[tool.uv.sources]
+bar = { path = "../projects/bar", package = true }
+Similarly, a dependency with a workspace source can be virtual if it
+explicitly sets tool.uv.package = false. The workspace
+member will be built even if a build system is not declared.
Workspace members that are not dependencies can be virtual by default, e.g., if the parent
+pyproject.toml is:
[project]
+name = "parent"
+version = "1.0.0"
+dependencies = []
+
+[tool.uv.workspace]
+members = ["child"]
+And the child pyproject.toml excluded a build system:
Then the child workspace member would not be installed, but the transitive dependency anyio
+would be.
In contrast, if the parent declared a dependency on child:
[project]
+name = "parent"
+version = "1.0.0"
+dependencies = ["child"]
+
+[tool.uv.sources]
+child = { workspace = true }
+
+[tool.uv.workspace]
+members = ["child"]
+Then child would be built and installed.
uv uses standard +dependency specifiers, +originally defined in PEP 508. A dependency specifier is +composed of, in order:
+The version specifiers are comma separated and added together, e.g., foo >=1.2.3,<2,!=1.4.0 is
+interpreted as "a version of foo that's at least 1.2.3, but less than 2, and not 1.4.0".
Specifiers are padded with trailing zeros if required, so foo ==2 matches foo 2.0.0, too.
A star can be used for the last digit with equals, e.g., foo ==2.1.* will accept any release from
+the 2.1 series. Similarly, ~= matches where the last digit is equal or higher, e.g., foo ~=1.2
+is equal to foo >=1.2,<2, and foo ~=1.2.3 is equal to foo >=1.2.3,<1.3.
Extras are comma-separated in square bracket between name and version, e.g.,
+pandas[excel,plot] ==2.2. Whitespace between extra names is ignored.
Some dependencies are only required in specific environments, e.g., a specific Python version or
+operating system. For example to install the importlib-metadata backport for the
+importlib.metadata module, use importlib-metadata >=7.1.0,<8; python_version < '3.10'. To
+install colorama on Windows (but omit it on other platforms), use
+colorama >=0.4.6,<5; platform_system == "Windows".
Markers are combined with and, or, and parentheses, e.g.,
+aiohttp >=3.7.4,<4; (sys_platform != 'win32' or implementation_name != 'pypy') and python_version >= '3.10'.
+Note that versions within markers must be quoted, while versions outside of markers must not be
+quoted.
Projects help manage Python code spanning multiple files.
+Tip
+Looking for an introduction to creating a project with uv? See the projects guide first.
+Working on projects is a core part of the uv experience. Learn more about using projects:
+uv supports creating a project with uv init.
When creating projects, uv supports two basic templates: applications and
+libraries. By default, uv will create a project for an application. The --lib
+flag can be used to create a project for a library instead.
uv will create a project in the working directory, or, in a target directory by providing a name,
+e.g., uv init foo. If there's already a project in the target directory, i.e., if there's a
+pyproject.toml, uv will exit with an error.
Application projects are suitable for web servers, scripts, and command-line interfaces.
+Applications are the default target for uv init, but can also be specified with the --app flag.
The project includes a pyproject.toml, a sample file (main.py), a readme, and a Python version
+pin file (.python-version).
$ tree example-app
+example-app
+├── .python-version
+├── README.md
+├── main.py
+└── pyproject.toml
+Note
+Prior to v0.6.0, uv created a file named hello.py instead of main.py.
The pyproject.toml includes basic metadata. It does not include a build system, it is not a
+package and will not be installed into the environment:
[project]
+name = "example-app"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+The sample file defines a main function with some standard boilerplate:
Python files can be executed with uv run:
Many use-cases require a package. For example, if you are creating +a command-line interface that will be published to PyPI or if you want to define tests in a +dedicated directory.
+The --package flag can be used to create a packaged application:
The source code is moved into a src directory with a module directory and an __init__.py file:
$ tree example-pkg
+example-pkg
+├── .python-version
+├── README.md
+├── pyproject.toml
+└── src
+ └── example_pkg
+ └── __init__.py
+A build system is defined, so the project will be installed into the +environment:
+[project]
+name = "example-pkg"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.scripts]
+example-pkg = "example_pkg:main"
+
+[build-system]
+requires = ["uv_build>=0.9.8,<0.10.0"]
+build-backend = "uv_build"
+Tip
+The --build-backend option can be used to request an alternative build system.
A command definition is included:
+[project]
+name = "example-pkg"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.scripts]
+example-pkg = "example_pkg:main"
+
+[build-system]
+requires = ["uv_build>=0.9.8,<0.10.0"]
+build-backend = "uv_build"
+The command can be executed with uv run:
A library provides functions and objects for other projects to consume. Libraries are intended to be +built and distributed, e.g., by uploading them to PyPI.
+Libraries can be created by using the --lib flag:
Note
+Using --lib implies --package. Libraries always require a packaged project.
As with a packaged application, a src layout is used. A py.typed
+marker is included to indicate to consumers that types can be read from the library:
$ tree example-lib
+example-lib
+├── .python-version
+├── README.md
+├── pyproject.toml
+└── src
+ └── example_lib
+ ├── py.typed
+ └── __init__.py
+Note
+A src layout is particularly valuable when developing libraries. It ensures that the library is
+isolated from any python invocations in the project root and that distributed library code is
+well separated from the rest of the project source.
A build system is defined, so the project will be installed into the +environment:
+[project]
+name = "example-lib"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.9.8,<0.10.0"]
+build-backend = "uv_build"
+Tip
+You can select a different build backend template by using --build-backend with hatchling,
+uv_build, flit-core, pdm-backend, setuptools, maturin, or scikit-build-core. An
+alternative backend is required if you want to create a library with extension modules.
The created module defines a simple API function:
+ +And you can import and execute it using uv run:
$ cd example-lib
+$ uv run python -c "import example_lib; print(example_lib.hello())"
+Hello from example-lib!
+Most Python projects are "pure Python", meaning they do not define modules in other languages like +C, C++, FORTRAN, or Rust. However, projects with extension modules are often used for performance +sensitive code.
+Creating a project with an extension module requires choosing an alternative build system. uv +supports creating projects with the following build systems that support building extension modules:
+maturin for projects with Rustscikit-build-core for projects with C, C++,
+ FORTRAN, CythonSpecify the build system with the --build-backend flag:
Note
+Using --build-backend implies --package.
The project contains a Cargo.toml and a lib.rs file in addition to the typical Python project
+files:
$ tree example-ext
+example-ext
+├── .python-version
+├── Cargo.toml
+├── README.md
+├── pyproject.toml
+└── src
+ ├── lib.rs
+ └── example_ext
+ ├── __init__.py
+ └── _core.pyi
+Note
+If using scikit-build-core, you'll see CMake configuration and a main.cpp file instead.
The Rust library defines a simple function:
+use pyo3::prelude::*;
+
+#[pymodule]
+mod _core {
+ use pyo3::prelude::*;
+
+ #[pyfunction]
+ fn hello_from_bin() -> String {
+ "Hello from example-ext!".to_string()
+ }
+}
+And the Python module imports it:
+from example_ext._core import hello_from_bin
+
+
+def main() -> None:
+ print(hello_from_bin())
+The command can be executed with uv run:
Important
+When creating a project with maturin or scikit-build-core, uv configures tool.uv.cache-keys
+to include common source file types. To force a rebuild, e.g. when changing files outside
+cache-keys or when not using cache-keys, use --reinstall.
If you only want to create a pyproject.toml, use the --bare option:
uv will skip creating a Python version pin file, a README, and any source directories or files.
+Additionally, uv will not initialize a version control system (i.e., git).
uv will also not add extra metadata to the pyproject.toml, such as the description or authors.
The --bare option can be used with other options like --lib or --build-backend — in these
+cases uv will still configure a build system but will not create the expected file structure.
When --bare is used, additional features can still be used opt-in:
pyproject.tomlPython project metadata is defined in a
+pyproject.toml file. uv
+requires this file to identify the root directory of a project.
Tip
+uv init can be used to create a new project. See Creating projects for
+details.
A minimal project definition includes a name and version:
+ +Additional project metadata and configuration includes:
+ +When working on a project with uv, uv will create a virtual environment as needed. While some uv
+commands will create a temporary environment (e.g., uv run --isolated), uv also manages a
+persistent environment with the project and its dependencies in a .venv directory next to the
+pyproject.toml. It is stored inside the project to make it easy for editors to find — they need
+the environment to give code completions and type hints. It is not recommended to include the
+.venv directory in version control; it is automatically excluded from git with an internal
+.gitignore file.
To run a command in the project environment, use uv run. Alternatively the project environment can
+be activated as normal for a virtual environment.
When uv run is invoked, it will create the project environment if it does not exist yet or ensure
+it is up-to-date if it exists. The project environment can also be explicitly created with
+uv sync. See the locking and syncing documentation for details.
It is not recommended to modify the project environment manually, e.g., with uv pip install. For
+project dependencies, use uv add to add a package to the environment. For one-off requirements,
+use uvx or
+uv run --with.
Tip
+If you don't want uv to manage the project environment, set managed = false
+to disable automatic locking and syncing of the project. For example:
uv creates a uv.lock file next to the pyproject.toml.
uv.lock is a universal or cross-platform lockfile that captures the packages that would be
+installed across all possible Python markers such as operating system, architecture, and Python
+version.
Unlike the pyproject.toml, which is used to specify the broad requirements of your project, the
+lockfile contains the exact resolved versions that are installed in the project environment. This
+file should be checked into version control, allowing for consistent and reproducible installations
+across machines.
A lockfile ensures that developers working on the project are using a consistent set of package +versions. Additionally, it ensures when deploying the project as an application that the exact set +of used package versions is known.
+The lockfile is automatically created and updated during uv
+invocations that use the project environment, i.e., uv sync and uv run. The lockfile may also be
+explicitly updated using uv lock.
uv.lock is a human-readable TOML file but is managed by uv and should not be edited manually. The
+uv.lock format is specific to uv and not usable by other tools.
pylock.tomlIn PEP 751, Python standardized a new resolution file format,
+pylock.toml.
pylock.toml is a resolution output format intended to replace requirements.txt (e.g., in the
+context of uv pip compile, whereby a "locked" requirements.txt file is generated from a set of
+input requirements). pylock.toml is standardized and tool-agnostic, such that in the future,
+pylock.toml files generated by uv could be installed by other tools, and vice versa.
Some of uv's functionality cannot be expressed in the pylock.toml format; as such, uv will
+continue to use the uv.lock format within the project interface.
However, uv supports pylock.toml as an export target and in the uv pip CLI. For example:
uv.lock to the pylock.toml format, run: uv export -o pylock.tomlpylock.toml file from a set of requirements, run:
+ uv pip compile requirements.in -o pylock.tomlpylock.toml file, run: uv pip sync pylock.toml or
+ uv pip install -r pylock.tomlWhen working on a project, it is installed into the virtual environment at .venv. This environment
+is isolated from the current shell by default, so invocations that require the project, e.g.,
+python -c "import example", will fail. Instead, use uv run to run commands in the project
+environment:
When using run, uv will ensure that the project environment is up-to-date before running the given
+command.
The given command can be provided by the project environment or exist outside of it, e.g.:
+$ # Presuming the project provides `example-cli`
+$ uv run example-cli foo
+
+$ # Running a `bash` script that requires the project to be available
+$ uv run bash scripts/foo.sh
+Additional dependencies or different versions of dependencies can be requested per invocation.
+The --with option is used to include a dependency for the invocation, e.g., to request a different
+version of httpx:
$ uv run --with httpx==0.26.0 python -c "import httpx; print(httpx.__version__)"
+0.26.0
+$ uv run --with httpx==0.25.0 python -c "import httpx; print(httpx.__version__)"
+0.25.0
+The requested version will be respected regardless of the project's requirements. For example, even
+if the project requires httpx==0.24.0, the output above would be the same.
Scripts that declare inline metadata are automatically executed in environments isolated from the +project. See the scripts guide for more +details.
+For example, given a script:
+# /// script
+# dependencies = [
+# "httpx",
+# ]
+# ///
+
+import httpx
+
+resp = httpx.get("https://peps.python.org/api/peps.json")
+data = resp.json()
+print([(k, v["title"]) for k, v in data.items()][:10])
+The invocation uv run example.py would run isolated from the project with only the given
+dependencies listed.
Support is provided for
+legacy setuptools scripts.
+These types of scripts are additional files installed by setuptools in .venv\Scripts.
Currently only legacy scripts with the .ps1, .cmd, and .bat extensions are supported.
For example, below is an example running a Command Prompt script.
+ +In addition, you don't need to specify the extension. uv will automatically look for files ending
+in .ps1, .cmd, and .bat in that order of execution on your behalf.
uv does not cede control of the process to the spawned command in order to provide better error +messages on failure. Consequently, uv is responsible for forwarding some signals to the child +process the requested command runs in.
+On Unix systems, uv will forward most signals (with the exception of SIGKILL, SIGCHLD, SIGIO, and +SIGPOLL) to the child process. Since terminals send SIGINT to the foreground process group on +Ctrl-C, uv will only forward a SIGINT to the child process if it is sent more than once or the child +process group differs from uv's.
+On Windows, these concepts do not apply and uv ignores Ctrl-C events, deferring handling to the +child process so it can exit cleanly.
+ + + + + + + + + + + + + + + + + +Locking is the process of resolving your project's dependencies into a +lockfile. Syncing is the process of installing a subset of packages from +the lockfile into the project environment.
+Locking and syncing are automatic in uv. For example, when uv run is used, the project is locked
+and synced before invoking the requested command. This ensures the project environment is always
+up-to-date. Similarly, commands which read the lockfile, such as uv tree, will automatically
+update it before running.
To disable automatic locking, use the --locked option:
If the lockfile is not up-to-date, uv will raise an error instead of updating the lockfile.
+To use the lockfile without checking if it is up-to-date, use the --frozen option:
Similarly, to run a command without checking if the environment is up-to-date, use the --no-sync
+option:
When considering if the lockfile is up-to-date, uv will check if it matches the project metadata.
+For example, if you add a dependency to your pyproject.toml, the lockfile will be considered
+outdated. Similarly, if you change the version constraints for a dependency such that the locked
+version is excluded, the lockfile will be considered outdated. However, if you change the version
+constraints such that the existing locked version is still included, the lockfile will still be
+considered up-to-date.
You can check if the lockfile is up-to-date by passing the --check flag to uv lock:
This is equivalent to the --locked flag for other commands.
Important
+uv will not consider lockfiles outdated when new versions of packages are released — the lockfile +needs to be explicitly updated if you want to upgrade dependencies. See the documentation on +upgrading locked package versions for details.
+While the lockfile is created automatically, the lockfile may also be
+explicitly created or updated using uv lock:
While the environment is synced automatically, it may also be explicitly
+synced using uv sync:
Syncing the environment manually is especially useful for ensuring your editor has the correct +versions of dependencies.
+When the environment is synced, uv will install the project (and other workspace members) as +editable packages, such that re-syncing is not necessary for changes to be reflected in the +environment.
+To opt-out of this behavior, use the --no-editable option.
Note
+If the project does not define a build system, it will not be installed. +See the build systems documentation for details.
+Syncing is "exact" by default, which means it will remove any packages that are not present in the +lockfile.
+To retain extraneous packages, use the --inexact option:
uv reads optional dependencies from the [project.optional-dependencies] table. These are
+frequently referred to as "extras".
uv does not sync extras by default. Use the --extra option to include an extra.
To quickly enable all extras, use the --all-extras option.
See the optional dependencies documentation for details +on how to manage optional dependencies.
+uv reads development dependencies from the [dependency-groups] table (as defined in
+PEP 735).
The dev group is special-cased and synced by default. See the
+default groups documentation for details on changing the
+defaults.
The --no-dev flag can be used to exclude the dev group.
The --only-dev flag can be used to install the dev group without the project and its
+dependencies.
Additional groups can be included or excluded with the --all-groups, --no-default-groups,
+--group <name>, --only-group <name>, and --no-group <name> options. The semantics of
+--only-group are the same as --only-dev, the project will not be included. However,
+--only-group will also exclude default groups.
Group exclusions always take precedence over inclusions, so given the command:
+ +The foo group would not be installed.
See the development dependencies documentation for +details on how to manage development dependencies.
+With an existing uv.lock file, uv will prefer the previously locked versions of packages when
+running uv sync and uv lock. Package versions will only change if the project's dependency
+constraints exclude the previous, locked version.
To upgrade all packages:
+ +To upgrade a single package to the latest version, while retaining the locked versions of all other +packages:
+ +To upgrade a single package to a specific version:
+ +In all cases, upgrades are limited to the project's dependency constraints. For example, if the +project defines an upper bound for a package then an upgrade will not go beyond that version.
+Note
+uv applies similar logic to Git dependencies. For example, if a Git dependency references
+the main branch, uv will prefer the locked commit SHA in an existing uv.lock file over
+the latest commit on the main branch, unless the --upgrade or --upgrade-package flags
+are used.
These flags can also be provided to uv sync or uv run to update the lockfile and the
+environment.
If you need to integrate uv with other tools or workflows, you can export uv.lock to the
+requirements.txt format with uv export --format requirements-txt. The generated
+requirements.txt file can then be installed via uv pip install, or with other tools like pip.
In general, we recommend against using both a uv.lock and a requirements.txt file. If you find
+yourself exporting a uv.lock file, consider opening an issue to discuss your use case.
Sometimes it's helpful to perform installations in multiple steps, e.g., for optimal layer caching
+while building a Docker image. uv sync has several flags for this purpose.
--no-install-project: Do not install the current project--no-install-workspace: Do not install any workspace members, including the root project--no-install-package <NO_INSTALL_PACKAGE>: Do not install the given package(s)When these options are used, all the dependencies of the target are still installed. For example,
+--no-install-project will omit the project but not any of its dependencies.
If used improperly, these flags can result in a broken environment since a package can be missing +its dependencies.
+ + + + + + + + + + + + + + + + + +Inspired by the Cargo concept of the +same name, a workspace is "a collection of one or more packages, called workspace members, that +are managed together."
+Workspaces organize large codebases by splitting them into multiple packages with common +dependencies. Think: a FastAPI-based web application, alongside a series of libraries that are +versioned and maintained as separate Python packages, all in the same Git repository.
+In a workspace, each package defines its own pyproject.toml, but the workspace shares a single
+lockfile, ensuring that the workspace operates with a consistent set of dependencies.
As such, uv lock operates on the entire workspace at once, while uv run and uv sync operate on
+the workspace root by default, though both accept a --package argument, allowing you to run a
+command in a particular workspace member from any workspace directory.
To create a workspace, add a tool.uv.workspace table to a pyproject.toml, which will implicitly
+create a workspace rooted at that package.
Tip
+By default, running uv init inside an existing package will add the newly created member to the workspace, creating a tool.uv.workspace table in the workspace root if it doesn't already exist.
In defining a workspace, you must specify the members (required) and exclude (optional) keys,
+which direct the workspace to include or exclude specific directories as members respectively, and
+accept lists of globs:
[project]
+name = "albatross"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = ["bird-feeder", "tqdm>=4,<5"]
+
+[tool.uv.sources]
+bird-feeder = { workspace = true }
+
+[tool.uv.workspace]
+members = ["packages/*"]
+exclude = ["packages/seeds"]
+Every directory included by the members globs (and not excluded by the exclude globs) must
+contain a pyproject.toml file. However, workspace members can be either
+applications or libraries; both are supported in
+the workspace context.
Every workspace needs a root, which is also a workspace member. In the above example, albatross
+is the workspace root, and the workspace members include all projects under the packages
+directory, except seeds.
By default, uv run and uv sync operates on the workspace root. For example, in the above
+example, uv run and uv run --package albatross would be equivalent, while
+uv run --package bird-feeder would run the command in the bird-feeder package.
Within a workspace, dependencies on workspace members are facilitated via
+tool.uv.sources, as in:
[project]
+name = "albatross"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = ["bird-feeder", "tqdm>=4,<5"]
+
+[tool.uv.sources]
+bird-feeder = { workspace = true }
+
+[tool.uv.workspace]
+members = ["packages/*"]
+
+[build-system]
+requires = ["uv_build>=0.9.8,<0.10.0"]
+build-backend = "uv_build"
+In this example, the albatross project depends on the bird-feeder project, which is a member of
+the workspace. The workspace = true key-value pair in the tool.uv.sources table indicates the
+bird-feeder dependency should be provided by the workspace, rather than fetched from PyPI or
+another registry.
Note
+Dependencies between workspace members are editable.
+Any tool.uv.sources definitions in the workspace root apply to all members, unless overridden in
+the tool.uv.sources of a specific member. For example, given the following pyproject.toml:
[project]
+name = "albatross"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = ["bird-feeder", "tqdm>=4,<5"]
+
+[tool.uv.sources]
+bird-feeder = { workspace = true }
+tqdm = { git = "https://github.com/tqdm/tqdm" }
+
+[tool.uv.workspace]
+members = ["packages/*"]
+
+[build-system]
+requires = ["uv_build>=0.9.8,<0.10.0"]
+build-backend = "uv_build"
+Every workspace member would, by default, install tqdm from GitHub, unless a specific member
+overrides the tqdm entry in its own tool.uv.sources table.
Note
+If a workspace member provides tool.uv.sources for some dependency, it will ignore any
+tool.uv.sources for the same dependency in the workspace root, even if the member's source is
+limited by a marker that doesn't match the current
+platform.
The most common workspace layout can be thought of as a root project with a series of accompanying +libraries.
+For example, continuing with the above example, this workspace has an explicit root at albatross,
+with two libraries (bird-feeder and seeds) in the packages directory:
albatross
+├── packages
+│ ├── bird-feeder
+│ │ ├── pyproject.toml
+│ │ └── src
+│ │ └── bird_feeder
+│ │ ├── __init__.py
+│ │ └── foo.py
+│ └── seeds
+│ ├── pyproject.toml
+│ └── src
+│ └── seeds
+│ ├── __init__.py
+│ └── bar.py
+├── pyproject.toml
+├── README.md
+├── uv.lock
+└── src
+ └── albatross
+ └── main.py
+Since seeds was excluded in the pyproject.toml, the workspace has two members total: albatross
+(the root) and bird-feeder.
Workspaces are intended to facilitate the development of multiple interconnected packages within a +single repository. As a codebase grows in complexity, it can be helpful to split it into smaller, +composable packages, each with their own dependencies and version constraints.
+Workspaces help enforce isolation and separation of concerns. For example, in uv, we have separate +packages for the core library and the command-line interface, enabling us to test the core library +independently of the CLI, and vice versa.
+Other common use cases for workspaces include:
+Workspaces are not suited for cases in which members have conflicting requirements, or desire a
+separate virtual environment for each member. In this case, path dependencies are often preferable.
+For example, rather than grouping albatross and its members in a workspace, you can always define
+each package as its own independent project, with inter-package dependencies defined as path
+dependencies in tool.uv.sources:
[project]
+name = "albatross"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = ["bird-feeder", "tqdm>=4,<5"]
+
+[tool.uv.sources]
+bird-feeder = { path = "packages/bird-feeder" }
+
+[build-system]
+requires = ["uv_build>=0.9.8,<0.10.0"]
+build-backend = "uv_build"
+This approach conveys many of the same benefits, but allows for more fine-grained control over
+dependency resolution and virtual environment management (with the downside that uv run --package
+is no longer available; instead, commands must be run from the relevant package directory).
Finally, uv's workspaces enforce a single requires-python for the entire workspace, taking the
+intersection of all members' requires-python values. If you need to support testing a given member
+on a Python version that isn't supported by the rest of the workspace, you may need to use uv pip
+to install that member in a separate virtual environment.
Note
+As Python does not provide dependency isolation, uv can't ensure that a package uses its declared dependencies and nothing else. For workspaces specifically, uv can't ensure that packages don't import dependencies declared by another workspace member.
+A Python version is composed of a Python interpreter (i.e. the python executable), the standard
+library, and other supporting files.
Since it is common for a system to have an existing Python installation, uv supports +discovering Python versions. However, uv also supports +installing Python versions itself. To distinguish between these two +types of Python installations, uv refers to Python versions it installs as managed Python +installations and all other Python installations as system Python installations.
+Note
+uv does not distinguish between Python versions installed by the operating system vs those
+installed and managed by other tools. For example, if a Python installation is managed with
+pyenv, it would still be considered a system Python version in uv.
A specific Python version can be requested with the --python flag in most uv commands. For
+example, when creating a virtual environment:
uv will ensure that Python 3.11.6 is available — downloading and installing it if necessary — then +create the virtual environment with it.
+The following Python version request formats are supported:
+<version> (e.g., 3, 3.12, 3.12.3)<version-specifier> (e.g., >=3.12,<3.13)<version><short-variant> (e.g., 3.13t, 3.12.0d)<version>+<variant> (e.g., 3.13+freethreaded, 3.12.0+debug)<implementation> (e.g., cpython or cp)<implementation>@<version> (e.g., cpython@3.12)<implementation><version> (e.g., cpython3.12 or cp312)<implementation><version-specifier> (e.g., cpython>=3.12,<3.13)<implementation>-<version>-<os>-<arch>-<libc> (e.g., cpython-3.12.3-macos-aarch64-none)Additionally, a specific system Python interpreter can be requested with:
+<executable-path> (e.g., /opt/homebrew/bin/python3)<executable-name> (e.g., mypython3)<install-dir> (e.g., /some/environment/)By default, uv will automatically download Python versions if they cannot be found on the system.
+This behavior can be
+disabled with the python-downloads option.
The .python-version file can be used to create a default Python version request. uv searches for a
+.python-version file in the working directory and each of its parents. If none is found, uv will
+check the user-level configuration directory. Any of the request formats described above can be
+used, though use of a version number is recommended for interoperability with other tools.
A .python-version file can be created in the current directory with the
+uv python pin command.
A global .python-version file can be created in the user configuration directory with the
+uv python pin --global command.
Discovery of .python-version files can be disabled with --no-config.
uv will not search for .python-version files beyond project or workspace boundaries (except the
+user configuration directory).
uv bundles a list of downloadable CPython and PyPy distributions for macOS, Linux, and Windows.
+Tip
+By default, Python versions are automatically downloaded as needed without using
+uv python install.
To install a Python version at a specific version:
+ +To install the latest patch version:
+ +To install a version that satisfies constraints:
+ +To install multiple versions:
+ +To install a specific implementation:
+ +All the Python version request formats are supported except those that are +used for requesting local interpreters such as a file path.
+By default uv python install will verify that a managed Python version is installed or install the
+latest version. If a .python-version file is present, uv will install the Python version listed in
+the file. A project that requires multiple Python versions may define a .python-versions file. If
+present, uv will install all the Python versions listed in the file.
Important
+The available Python versions are frozen for each uv release. To install new Python versions, +you may need upgrade uv.
+uv installs Python executables into your PATH by default, e.g., uv python install 3.12 will
+install a Python executable into ~/.local/bin, e.g., as python3.12.
Tip
+If ~/.local/bin is not in your PATH, you can add it with uv tool update-shell.
To install python and python3 executables, include the experimental --default option:
When installing Python executables, uv will only overwrite an existing executable if it is managed
+by uv — e.g., if ~/.local/bin/python3.12 exists already uv will not overwrite it without the
+--force flag.
uv will update executables that it manages. However, it will prefer the latest patch version of each +Python minor version by default. For example:
+$ uv python install 3.12.7 # Adds `python3.12` to `~/.local/bin`
+$ uv python install 3.12.6 # Does not update `python3.12`
+$ uv python install 3.12.8 # Updates `python3.12` to point to 3.12.8
+Important
+Support for upgrading Python versions is in preview. This means the behavior is experimental +and subject to change.
+Upgrades are only supported for uv-managed Python versions.
+Upgrades are not currently supported for PyPy and GraalPy.
+uv allows transparently upgrading Python versions to the latest patch release, e.g., 3.13.4 to +3.13.5. uv does not allow transparently upgrading across minor Python versions, e.g., 3.12 to 3.13, +because changing minor versions can affect dependency resolution.
+uv-managed Python versions can be upgraded to the latest supported patch release with the
+python upgrade command:
To upgrade a Python version to the latest supported patch release:
+ +To upgrade all installed Python versions:
+ +After an upgrade, uv will prefer the new version, but will retain the existing version as it may +still be used by virtual environments.
+If the Python version was installed with the python-upgrade preview feature
+enabled, e.g., uv python install 3.12 --preview-features python-upgrade, virtual environments
+using the Python version will be automatically upgraded to the new patch version.
Note
+If the virtual environment was created before opting in to the preview mode, it will not be +included in the automatic upgrades.
+If a virtual environment was created with an explicitly requested patch version, e.g.,
+uv venv -p 3.10.8, it will not be transparently upgraded to a new version.
Automatic upgrades for virtual environments are implemented using a directory with the Python minor +version, e.g.:
+ +which is a symbolic link (on Unix) or junction (on Windows) pointing to a specific patch version:
+$ readlink ~/.local/share/uv/python/cpython-3.12-macos-aarch64-none
+~/.local/share/uv/python/cpython-3.12.11-macos-aarch64-none
+If this link is resolved by another tool, e.g., by canonicalizing the Python interpreter path, and +used to create a virtual environment, it will not be automatically upgraded.
+uv will respect Python requirements defined in requires-python in the pyproject.toml file during
+project command invocations. The first Python version that is compatible with the requirement will
+be used, unless a version is otherwise requested, e.g., via a .python-version file or the
+--python flag.
To list installed and available Python versions:
+ +To filter the Python versions, provide a request, e.g., to show all Python 3.13 interpreters:
+ +Or, to show all PyPy interpreters:
+ +By default, downloads for other platforms and old patch versions are hidden.
+To view all versions:
+ +To view Python versions for other platforms:
+ +To exclude downloads and only show installed Python versions:
+ +See the uv python list reference for more details.
To find a Python executable, use the uv python find command:
By default, this will display the path to the first available Python executable. See the +discovery rules for details about how executables are discovered.
+This interface also supports many request formats, e.g., to find a Python +executable that has a version of 3.11 or newer:
+ +By default, uv python find will include Python versions from virtual environments. If a .venv
+directory is found in the working directory or any of the parent directories or the VIRTUAL_ENV
+environment variable is set, it will take precedence over any Python executables on the PATH.
To ignore virtual environments, use the --system flag:
When searching for a Python version, the following locations are checked:
+UV_PYTHON_INSTALL_DIR.PATH as python, python3, or python3.x on macOS and Linux, or
+ python.exe on Windows.py --list-paths) that match the requested version.In some cases, uv allows using a Python version from a virtual environment. In this case, the +virtual environment's interpreter will be checked for compatibility with the request before +searching for an installation as described above. See the +pip-compatible virtual environment discovery +documentation for details.
+When performing discovery, non-executable files will be ignored. Each discovered executable is +queried for metadata to ensure it meets the requested Python version. If +the query fails, the executable will be skipped. If the executable satisfies the request, it is used +without inspecting additional executables.
+When searching for a managed Python version, uv will prefer newer versions first. When searching for +a system Python version, uv will use the first compatible version — not the newest version.
+If a Python version cannot be found on the system, uv will check for a compatible managed Python +version download.
+Python pre-releases will not be selected by default. Python pre-releases will be used if there is no +other available installation matching the request. For example, if only a pre-release version is +available it will be used but otherwise a stable release version will be used. Similarly, if the +path to a pre-release Python executable is provided then no other Python version matches the request +and the pre-release version will be used.
+If a pre-release Python version is available and matches the request, uv will not download a stable +Python version instead.
+uv supports discovering and installing +free-threaded Python variants in +CPython 3.13+.
+Free-threaded Python versions will not be selected by default. Free-threaded Python versions will
+only be selected when explicitly requested, e.g., with 3.13t or 3.13+freethreaded.
uv supports discovering and installing +debug builds of Python, i.e., with +debug assertions enabled.
+Important
+Debug builds of Python are slower and are not appropriate for general use.
+Debug builds will be used if there is no other available installation matching the request. For +example, if only a debug version is available it will be used but otherwise a stable release version +will be used. Similarly, if the path to a debug Python executable is provided then no other Python +version matches the request and the debug version will be used.
+Debug builds of Python can be explicitly requested with, e.g., 3.13d or 3.13+debug.
Note
+CPython versions installed by uv usually have debug symbols stripped to reduce the distribution +size. These debug builds do not have debug symbols stripped, which can be useful when debugging +Python processes with a C-level debugger.
+By default, uv will automatically download Python versions when needed.
+The python-downloads option can be used to disable
+this behavior. By default, it is set to automatic; set to manual to only allow Python downloads
+during uv python install.
Tip
+The python-downloads setting can be set in a
+persistent configuration file to change the default behavior, or
+the --no-python-downloads flag can be passed to any uv command.
By default, uv will attempt to use Python versions found on the system and only download managed
+Python versions when necessary. To ignore system Python versions, and only use managed Python
+versions, use the --managed-python flag:
Similarly, to ignore managed Python versions and only use system Python versions, use the
+--no-managed-python flag:
To change uv's default behavior in a configuration file, use the
+python-preference setting.
The python-preference setting determines whether to
+prefer using Python installations that are already present on the system, or those that are
+downloaded and installed by uv.
By default, the python-preference is set to managed which prefers managed Python installations
+over system Python installations. However, system Python installations are still preferred over
+downloading a managed Python version.
The following alternative options are available:
+only-managed: Only use managed Python installations; never use system Python installations.
+ Equivalent to --managed-python.system: Prefer system Python installations over managed Python installations.only-system: Only use system Python installations; never use managed Python installations.
+ Equivalent to --no-managed-python.Note
+Automatic Python version downloads can be disabled +without changing the preference.
+uv supports the CPython, PyPy, Pyodide, and GraalPy Python implementations. If a Python +implementation is not supported, uv will fail to discover its interpreter.
+The implementations may be requested with either the long or short name:
+cpython, cppypy, ppgraalpy, gppyodideImplementation name requests are not case-sensitive.
+See the Python version request documentation for more details on the +supported formats.
+uv supports downloading and installing CPython, PyPy, and Pyodide distributions.
+As Python does not publish official distributable CPython binaries, uv instead uses pre-built
+distributions from the Astral
+python-build-standalone project.
+python-build-standalone is also is used in many other Python projects, like
+Mise and
+bazelbuild/rules_python.
The uv Python distributions are self-contained, highly-portable, and performant. While Python can be
+built from source, as in tools like pyenv, doing so requires preinstalled system dependencies, and
+creating optimized, performant builds (e.g., with PGO and LTO enabled) is very slow.
These distributions have some behavior quirks, generally as a consequence of portability; see the
+python-build-standalone quirks
+documentation for details.
PyPy distributions are provided by the PyPy project.
+Pyodide distributions are provided by the Pyodide project.
+Pyodide is a port of CPython for the WebAssembly / Emscripten platform.
+Both macOS and Windows support running x86_64 binaries on aarch64 through transparent emulation. +This is called Rosetta 2 or +Windows on ARM (WoA) emulation. +It's possible to use x86_64 uv on aarch64, and also possible to use an x86_64 Python interpreter on +aarch64. Either uv binary can use either Python interpreter, but a Python interpreter needs packages +for its architecture, either all x86_64 or all aarch64.
+On Windows, installation of managed Python versions will register them with the Windows registry as +defined by PEP 514.
+After installation, the Python versions can be selected with the py launcher, e.g.:
On uninstall, uv will remove the registry entry for the target version as well as any broken +registry entries.
+ + + + + + + + + + + + + + + + + +Resolution is the process of taking a list of requirements and converting them to a list of package +versions that fulfill the requirements. Resolution requires recursively searching for compatible +versions of packages, ensuring that the requested requirements are fulfilled and that the +requirements of the requested packages are compatible.
+Most projects and packages have dependencies. Dependencies are other packages that are necessary in +order for the current package to work. A package defines its dependencies as requirements, roughly +a combination of a package name and acceptable versions. The dependencies defined by the current +project are called direct dependencies. The dependencies added by each dependency of the current +project are called indirect or transitive dependencies.
+Note
+See the dependency specifiers +page +in the Python Packaging documentation for details about dependencies.
+To help demonstrate the resolution process, consider the following dependencies:
+ +foo and bar.foo has one version, 1.0.0:foo 1.0.0 depends on lib>=1.0.0.bar has one version, 1.0.0:bar 1.0.0 depends on lib>=2.0.0.lib has two versions, 1.0.0 and 2.0.0. Both versions have no dependencies.In this example, the resolver must find a set of package versions which satisfies the project
+requirements. Since there is only one version of both foo and bar, those will be used. The
+resolution must also include the transitive dependencies, so a version of lib must be chosen.
+foo 1.0.0 allows all available versions of lib, but bar 1.0.0 requires lib>=2.0.0 so
+lib 2.0.0 must be used.
In some resolutions, there may be more than one valid solution. Consider the following dependencies:
+ +foo and bar.foo has two versions, 1.0.0 and 2.0.0:foo 1.0.0 has no dependencies.foo 2.0.0 depends on lib==2.0.0.bar has two versions, 1.0.0 and 2.0.0:bar 1.0.0 has no dependencies.bar 2.0.0 depends on lib==1.0.0lib has two versions, 1.0.0 and 2.0.0. Both versions have no dependencies.In this example, some version of both foo and bar must be selected; however, determining which
+version requires considering the dependencies of each version of foo and bar. foo 2.0.0 and
+bar 2.0.0 cannot be installed together as they conflict on their required version of lib, so the
+resolver must select either foo 1.0.0 (along with bar 2.0.0) or bar 1.0.0 (along with
+foo 1.0.0). Both are valid solutions, and different resolution algorithms may yield either result.
Markers allow attaching an expression to requirements that indicate when the dependency should be
+used. For example bar ; python_version < "3.9" indicates that bar should only be installed on
+Python 3.8 and earlier.
Markers are used to adjust a package's dependencies based on the current environment or platform. +For example, markers can be used to modify dependencies by operating system, CPU architecture, +Python version, Python implementation, and more.
+Note
+See the environment +markers +section in the Python Packaging documentation for more details about markers.
+Markers are important for resolution because their values change the required dependencies. +Typically, Python package resolvers use the markers of the current platform to determine which +dependencies to use since the package is often being installed on the current platform. However, +for locking dependencies this is problematic — the lockfile would only work for developers using +the same platform the lockfile was created on. To solve this problem, platform-independent, or +"universal" resolvers exist.
+uv supports both platform-specific and +universal resolution.
+By default, uv's pip interface, i.e., uv pip compile, produces a resolution
+that is platform-specific, like pip-tools. There is no way to use platform-specific resolution in
+the uv's project interface.
uv also supports resolving for specific, alternate platforms and Python versions with the
+--python-platform and --python-version options. For example, if using Python 3.12 on macOS,
+uv pip compile --python-platform linux --python-version 3.10 requirements.in can be used to
+produce a resolution for Python 3.10 on Linux instead. Unlike universal resolution, during
+platform-specific resolution, the provided --python-version is the exact python version to use,
+not a lower bound.
Note
+Python's environment markers expose far more information about the current machine
+than can be expressed by a simple --python-platform argument. For example, the platform_version marker
+on macOS includes the time at which the kernel was built, which can (in theory) be encoded in
+package requirements. uv's resolver makes a best-effort attempt to generate a resolution that is
+compatible with any machine running on the target --python-platform, which should be sufficient for
+most use cases, but may lose fidelity for complex package and platform combinations.
uv's lockfile (uv.lock) is created with a universal resolution and is portable across platforms.
+This ensures that dependencies are locked for everyone working on the project, regardless of
+operating system, architecture, and Python version. The uv lockfile is created and modified by
+project commands such as uv lock, uv sync, and uv add.
Universal resolution is also available in uv's pip interface, i.e.,
+uv pip compile, with the --universal flag. The resulting requirements file
+will contain markers to indicate which platform each dependency is relevant for.
During universal resolution, a package may be listed multiple times with different versions or URLs +if different versions are needed for different platforms — the markers determine which version will +be used. A universal resolution is often more constrained than a platform-specific resolution, since +we need to take the requirements for all markers into account.
+During universal resolution, all required packages must be compatible with the entire range of
+requires-python declared in the pyproject.toml. For example, if a project's requires-python is
+>=3.8, resolution will fail if all versions of given dependency require Python 3.9 or later, since
+the dependency lacks a usable version for (e.g.) Python 3.8, the lower bound of the project's
+supported range. In other words, the project's requires-python must be a subset of the
+requires-python of all its dependencies.
When selecting the compatible version for a given dependency, uv will
+(by default) attempt to choose the latest compatible version for each
+supported Python version. For example, if a project's requires-python is >=3.8, and the latest
+version of a dependency requires Python 3.9 or later, while all prior versions supporting Python
+3.8, the resolver will select the latest version for users running Python 3.9 or later, and previous
+versions for users running Python 3.8.
When evaluating requires-python ranges for dependencies, uv only considers lower bounds and
+ignores upper bounds entirely. For example, >=3.8, <4 is treated as >=3.8. Respecting upper
+bounds on requires-python often leads to formally correct but practically incorrect resolutions,
+as, e.g., resolvers will backtrack to the first published version that omits the upper bound (see:
+Requires-Python upper limits).
By default, the universal resolver attempts to solve for all platforms and Python versions.
+If your project supports only a limited set of platforms or Python versions, you can constrain the
+set of solved platforms via the environments setting, which accepts a list of
+PEP 508 environment markers.
+In other words, you can use the environments setting to reduce the set of supported platforms.
For example, to constrain the lockfile to macOS and Linux, and avoid solving for Windows:
+[tool.uv]
+environments = [
+ "sys_platform == 'darwin'",
+ "sys_platform == 'linux'",
+]
+Or, to avoid solving for alternative Python implementations:
+ +Entries in the environments setting must be disjoint (i.e., they must not overlap). For example,
+sys_platform == 'darwin' and sys_platform == 'linux' are disjoint, but
+sys_platform == 'darwin' and python_version >= '3.9' are not, since both could be true at the
+same time.
In the Python ecosystem, packages can be published as source distributions, built distributions +(wheels), or both; but to install a package, a built distribution is required. If a package lacks a +built distribution, or lacks a distribution for the current platform or Python version (built +distributions are often platform-specific), uv will attempt to build the package from source, then +install the resulting built distribution.
+Some packages (like PyTorch) publish built distributions, but omit a source distribution. Such +packages are only installable on platforms for which a built distribution is available. For +example, if a package publishes built distributions for Linux, but not macOS or Windows, then that +package will only be installable on Linux.
+Packages that lack source distributions cause problems for universal resolution, since there will +typically be at least one platform or Python version for which the package is not installable.
+By default, uv requires each such package to include at least one wheel that is compatible with the
+target Python version. The required-environments setting can be used to ensure that the resulting
+resolution contains wheels for specific platforms, or fails if no such wheels are available. The
+setting accepts a list of
+PEP 508 environment markers.
While the environments setting limits the set of environments that uv will consider when
+resolving dependencies, required-environments expands the set of platforms that uv must
+support when resolving dependencies.
For example, environments = ["sys_platform == 'darwin'"] would limit uv to solving for macOS (and
+ignoring Linux and Windows). On the other hand,
+required-environments = ["sys_platform == 'darwin'"] would require that any package without a
+source distribution include a wheel for macOS in order to be installable (and would fail if no such
+wheel is available).
In practice, required-environments can be useful for declaring explicit support for non-latest
+platforms, since this often requires backtracking past the latest published versions of those
+packages. For example, to guarantee that any built distribution-only packages includes support for
+Intel macOS:
[tool.uv]
+required-environments = [
+ "sys_platform == 'darwin' and platform_machine == 'x86_64'"
+]
+If resolution output file exists, i.e., a uv lockfile (uv.lock) or a requirements output file
+(requirements.txt), uv will prefer the dependency versions listed there. Similarly, if
+installing a package into a virtual environment, uv will prefer the already installed version if
+present. This means that locked or installed versions will not change unless an incompatible version
+is requested or an upgrade is explicitly requested with --upgrade.
By default, uv tries to use the latest version of each package. For example,
+uv pip install flask>=2.0.0 will install the latest version of Flask, e.g., 3.0.0. If
+flask>=2.0.0 is a dependency of the project, only flask 3.0.0 will be used. This is important,
+for example, because running tests will not check that the project is actually compatible with its
+stated lower bound of flask 2.0.0.
With --resolution lowest, uv will install the lowest possible version for all dependencies, both
+direct and indirect (transitive). Alternatively, --resolution lowest-direct will use the lowest
+compatible versions for all direct dependencies, while using the latest compatible versions for all
+other dependencies. uv will always use the latest versions for build dependencies.
For example, given the following requirements.in file:
Running uv pip compile requirements.in would produce the following requirements.txt file:
# This file was autogenerated by uv via the following command:
+# uv pip compile requirements.in
+blinker==1.7.0
+ # via flask
+click==8.1.7
+ # via flask
+flask==3.0.0
+itsdangerous==2.1.2
+ # via flask
+jinja2==3.1.2
+ # via flask
+markupsafe==2.1.3
+ # via
+ # jinja2
+ # werkzeug
+werkzeug==3.0.1
+ # via flask
+However, uv pip compile --resolution lowest requirements.in would instead produce:
# This file was autogenerated by uv via the following command:
+# uv pip compile requirements.in --resolution lowest
+click==7.1.2
+ # via flask
+flask==2.0.0
+itsdangerous==2.0.0
+ # via flask
+jinja2==3.0.0
+ # via flask
+markupsafe==2.0.0
+ # via jinja2
+werkzeug==2.0.0
+ # via flask
+When publishing libraries, it is recommended to separately run tests with --resolution lowest or
+--resolution lowest-direct in continuous integration to ensure compatibility with the declared
+lower bounds.
By default, uv will accept pre-release versions during dependency resolution in two cases:
+flask>=2.0.0rc1).If dependency resolution fails due to a transitive pre-release, uv will prompt use of
+--prerelease allow to allow pre-releases for all dependencies.
Alternatively, the transitive dependency can be added as a constraint or
+direct dependency (i.e. in requirements.in or pyproject.toml) with a pre-release version
+specifier (e.g., flask>=2.0.0rc1) to opt in to pre-release support for that specific dependency.
Pre-releases are +notoriously difficult to +model, and are a frequent source of bugs in other packaging tools. uv's pre-release handling is +intentionally limited and requires user opt-in for pre-releases to ensure correctness.
+For more details, see +Pre-release compatibility.
+During universal resolution, a package may be listed multiple times with different versions or URLs +within the same lockfile, since different versions may be needed for different platforms or Python +versions.
+The --fork-strategy setting can be used to control how uv trades off between (1) minimizing the
+number of selected versions and (2) selecting the latest-possible version for each platform. The
+former leads to greater consistency across platforms, while the latter leads to use of newer package
+versions where possible.
By default (--fork-strategy requires-python), uv will optimize for selecting the latest version of
+each package for each supported Python version, while minimizing the number of selected versions
+across platforms.
For example, when resolving numpy with a Python requirement of >=3.8, uv would select the
+following versions:
numpy==1.24.4 ; python_version == "3.8"
+numpy==2.0.2 ; python_version == "3.9"
+numpy==2.2.0 ; python_version >= "3.10"
+This resolution reflects the fact that NumPy 2.2.0 and later require at least Python 3.10, while +earlier versions are compatible with Python 3.8 and 3.9.
+Under --fork-strategy fewest, uv will instead 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.
For example, when in the scenario above, uv would select numpy==1.24.4 for all Python versions,
+rather than upgrading to numpy==2.0.2 for Python 3.9 and numpy==2.2.0 for Python 3.10 and later.
Like pip, uv supports constraint files (--constraint constraints.txt) which narrow the set of
+acceptable versions for the given packages. Constraint files are similar to requirements files, but
+being listed as a constraint alone will not cause a package to be included to the resolution.
+Instead, constraints only take effect if a requested package is already pulled in as a direct or
+transitive dependency. Constraints are useful for reducing the range of available versions for a
+transitive dependency. They can also be used to keep a resolution in sync with some other set of
+resolved versions, regardless of which packages are overlapping between the two.
Dependency overrides allow bypassing unsuccessful or undesirable resolutions by overriding a +package's declared dependencies. Overrides are a useful last resort for cases in which you know +that a dependency is compatible with a certain version of a package, despite the metadata indicating +otherwise.
+For example, if a transitive dependency declares the requirement pydantic>=1.0,<2.0, but does
+work with pydantic>=2.0, the user can override the declared dependency by including
+pydantic>=1.0,<3 in the overrides, thereby allowing the resolver to choose a newer version of
+pydantic.
Concretely, if pydantic>=1.0,<3 is included as an override, uv will ignore all declared
+requirements on pydantic, replacing them with the override. In the above example, the
+pydantic>=1.0,<2.0 requirement would be ignored completely, and would instead be replaced with
+pydantic>=1.0,<3.
While constraints can only reduce the set of acceptable versions for a package, overrides can +expand the set of acceptable versions, providing an escape hatch for erroneous upper version +bounds. As with constraints, overrides do not add a dependency on the package and only take effect +if the package is requested in a direct or transitive dependency.
+In a pyproject.toml, use tool.uv.override-dependencies to define a list of overrides. In the
+pip-compatible interface, the --override option can be used to pass files with the same format as
+constraints files.
If multiple overrides are provided for the same package, they must be differentiated with +markers. If a package has a dependency with a marker, it is replaced +unconditionally when using overrides — it does not matter if the marker evaluates to true or false.
+During resolution, uv needs to resolve the metadata for each package it encounters, in order to +determine its dependencies. This metadata is often available as a static file in the package index; +however, for packages that only provide source distributions, the metadata may not be available +upfront.
+In such cases, uv has to build the package to determine its metadata (e.g., by invoking setup.py).
+This can introduce a performance penalty during resolution. Further, it imposes the requirement that
+the package can be built on all platforms, which may not be true.
For example, you may have a package that should only be built and installed on Linux, but doesn't +build successfully on macOS or Windows. While uv can construct a perfectly valid lockfile for this +scenario, doing so would require building the package, which would fail on non-Linux platforms.
+The tool.uv.dependency-metadata table can be used to provide static metadata for such dependencies
+upfront, thereby allowing uv to skip the build step and use the provided metadata instead.
For example, to provide metadata for chumpy upfront, include its dependency-metadata in the
+pyproject.toml:
[[tool.uv.dependency-metadata]]
+name = "chumpy"
+version = "0.70"
+requires-dist = ["numpy>=1.8.1", "scipy>=0.13.0", "six>=1.11.0"]
+These declarations are intended for cases in which a package does not declare static metadata +upfront, though they are also useful for packages that require +disabling build isolation In such cases, it may be easier to +declare the package metadata upfront, rather than creating a custom build environment prior to +resolving the package.
+For example, past versions of flash-attn did not declare static metadata. By declaring metadata
+for flash-attn upfront, uv can resolve flash-attn without building the package from source
+(which itself requires installing torch):
[project]
+name = "project"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = ["flash-attn"]
+
+[tool.uv.sources]
+flash-attn = { git = "https://github.com/Dao-AILab/flash-attention", tag = "v2.6.3" }
+
+[[tool.uv.dependency-metadata]]
+name = "flash-attn"
+version = "2.6.3"
+requires-dist = ["torch", "einops"]
+Like dependency overrides, tool.uv.dependency-metadata can also be used for cases in which a
+package's metadata is incorrect or incomplete, or when a package is not available in the package
+index. While dependency overrides allow overriding the allowed versions of a package globally,
+metadata overrides allow overriding the declared metadata of a specific package.
Note
+The version field in tool.uv.dependency-metadata is optional for registry-based
+dependencies (when omitted, uv will assume the metadata applies to all versions of the package),
+but required for direct URL dependencies (like Git dependencies).
Entries in the tool.uv.dependency-metadata table follow the
+Metadata 2.3 specification,
+though only name, version, requires-dist, requires-python, and provides-extra are read by
+uv. The version field is also considered optional. If omitted, the metadata will be used for all
+versions of the specified package.
uv requires that all dependencies declared by a project are compatible with each other and resolves +all dependencies together when creating the lockfile. This includes project dependencies, optional +dependencies ("extras"), and dependency groups (development dependencies).
+If dependencies declared in one extra are not compatible with those in another extra, uv will fail +to resolve the requirements of the project with an error. For example, consider two sets of optional +dependencies that conflict with one another:
+[project.optional-dependencies]
+extra1 = ["numpy==2.1.2"]
+extra2 = ["numpy==2.0.0"]
+If you run uv lock with the above dependencies, resolution will fail:
$ uv lock
+ x No solution found when resolving dependencies:
+ `-> Because myproject[extra2] depends on numpy==2.0.0 and myproject[extra1] depends on numpy==2.1.2, we can conclude that myproject[extra1] and
+ myproject[extra2] are incompatible.
+ And because your project requires myproject[extra1] and myproject[extra2], we can conclude that your projects's requirements are unsatisfiable.
+To work around this, uv supports explicit declaration of conflicts. If you specify that extra1 and
+extra2 are conflicting, uv will resolve them separately. Specify conflicts in the tool.uv
+section:
[tool.uv]
+conflicts = [
+ [
+ { extra = "extra1" },
+ { extra = "extra2" },
+ ],
+]
+Now, running uv lock will succeed. However, now you cannot install both extra1 and extra2 at
+the same time:
$ uv sync --extra extra1 --extra extra2
+Resolved 3 packages in 14ms
+error: extra `extra1`, extra `extra2` are incompatible with the declared conflicts: {`myproject[extra1]`, `myproject[extra2]`}
+This error occurs because installing both extra1 and extra2 would result in installing two
+different versions of a package into the same environment.
The above strategy for dealing with conflicting optional dependencies also works with dependency +groups:
+[dependency-groups]
+group1 = ["numpy==2.1.2"]
+group2 = ["numpy==2.0.0"]
+
+[tool.uv]
+conflicts = [
+ [
+ { group = "group1" },
+ { group = "group2" },
+ ],
+]
+The only difference from conflicting extras is that you need to use the group key instead of
+extra.
When using a workspace with multiple projects, the same restrictions apply — uv requires all +workspace members to be compatible with each other. Similarly, conflicts can be declared across +workspace members.
+For example, consider the following workspace:
+[project]
+name = "member1"
+
+[project.optional-dependencies]
+extra1 = ["numpy==2.1.2"]
+[project]
+name = "member2"
+
+[project.optional-dependencies]
+extra2 = ["numpy==2.0.0"]
+To declare a conflict between extras in these different workspace members, use the package key:
[tool.uv]
+conflicts = [
+ [
+ { package = "member1", extra = "extra1" },
+ { package = "member2", extra = "extra2" },
+ ],
+]
+It's also possible for the project dependencies (i.e., project.dependencies) of one workspace
+member to conflict with the extra of another member, for example:
[project]
+name = "member2"
+
+[project.optional-dependencies]
+extra2 = ["numpy==2.0.0"]
+This conflict can also be declared using the package key:
[tool.uv]
+conflicts = [
+ [
+ { package = "member1" },
+ { package = "member2", extra = "extra2" },
+ ],
+]
+Similarly, it's possible for some workspace members to have conflicting project dependencies:
+ + +This conflict can also be declared using the package key:
[tool.uv]
+conflicts = [
+ [
+ { package = "member1" },
+ { package = "member2" },
+ ],
+]
+These workspace members will not be installable together, e.g., the workspace root cannot define:
+ +By default, uv add adds lower bounds to dependencies and, when using uv to manage projects, uv
+will warn if direct dependencies don't have lower bound.
Lower bounds are not critical in the "happy path", but they are important for cases where there are +dependency conflicts. For example, consider a project that requires two packages and those packages +have conflicting dependencies. The resolver needs to check all combinations of all versions within +the constraints for the two packages — if all of them conflict, an error is reported because the +dependencies are not satisfiable. If there are no lower bounds, the resolver can (and often will) +backtrack down to the oldest version of a package. This isn't only problematic because it's slow, +the old version of the package often fails to build, or the resolver can end up picking a version +that's old enough that it doesn't depend on the conflicting package, but also doesn't work with your +code.
+Lower bounds are particularly critical when writing a library. It's important to declare the lowest
+version for each dependency that your library works with, and to validate that the bounds are
+correct — testing with
+--resolution lowest or --resolution lowest-direct. Otherwise, a user may
+receive an old, incompatible version of one of your library's dependencies and the library will fail
+with an unexpected error.
uv supports an --exclude-newer option to limit resolution to distributions published before a
+specific date, allowing reproduction of installations regardless of new package releases. The date
+may be specified as an RFC 3339 timestamp (e.g.,
+2006-12-02T02:07:43Z) or a local date in the same format (e.g., 2006-12-02) in your system's
+configured time zone.
Note the package index must support the upload-time field as specified in
+PEP 700. If the field is not present for a given
+distribution, the distribution will be treated as unavailable. PyPI provides upload-time for all
+packages.
To ensure reproducibility, messages for unsatisfiable resolutions will not mention that
+distributions were excluded due to the --exclude-newer flag — newer distributions will be treated
+as if they do not exist.
Note
+The --exclude-newer option is only applied to packages that are read from a registry (as opposed to, e.g., Git
+dependencies). Further, when using the uv pip interface, uv will not downgrade previously installed packages
+unless the --reinstall flag is provided, in which case uv will perform a new resolution.
PEP 625 specifies that packages must distribute source
+distributions as gzip tarball (.tar.gz) archives. Prior to this specification, other archive
+formats, which need to be supported for backward compatibility, were also allowed. uv supports
+reading and extracting archives in the following formats:
.tar.gz, .tgz).tar.bz2, .tbz).tar.xz, .txz).tar.zst).tar.lz).tar.lzma).zip)The uv.lock file uses a versioned schema. The schema version is included in the version field of
+the lockfile.
Any given version of uv can read and write lockfiles with the same schema version, but will reject
+lockfiles with a greater schema version. For example, if your uv version supports schema v1,
+uv lock will error if it encounters an existing lockfile with schema v2.
uv versions that support schema v2 may be able to read lockfiles with schema v1 if the schema +update was backwards-compatible. However, this is not guaranteed, and uv may exit with an error if +it encounters a lockfile with an outdated schema version.
+The schema version is considered part of the public API, and so is only bumped in minor releases, as +a breaking change (see Versioning). As such, all uv patch +versions within a given minor uv release are guaranteed to have full lockfile compatibility. In +other words, lockfiles may only be rejected across minor releases.
+The revision field of the lockfile is used to track backwards compatible changes to the lockfile.
+For example, adding a new field to distributions. Changes to the revision will not cause older
+versions of uv to error.
For more details about the internals of the resolver, see the +resolver reference documentation.
+ + + + + + + + + + + + + + + + + +Tools are Python packages that provide command-line interfaces.
+Note
+See the tools guide for an introduction to working with the tools +interface — this document discusses details of tool management.
+uv tool interfaceuv includes a dedicated interface for interacting with tools. Tools can be invoked without
+installation using uv tool run, in which case their dependencies are installed in a temporary
+virtual environment isolated from the current project.
Because it is very common to run tools without installing them, a uvx alias is provided for
+uv tool run — the two commands are exactly equivalent. For brevity, the documentation will mostly
+refer to uvx instead of uv tool run.
Tools can also be installed with uv tool install, in which case their executables are
+available on the PATH — an isolated virtual environment is still used, but it is not
+removed when the command completes.
In most cases, executing a tool with uvx is more appropriate than installing the tool. Installing
+the tool is useful if you need the tool to be available to other programs on your system, e.g., if
+some script you do not control requires the tool, or if you are in a Docker image and want to make
+the tool available to users.
When running a tool with uvx, a virtual environment is stored in the uv cache directory and is
+treated as disposable, i.e., if you run uv cache clean the environment will be deleted. The
+environment is only cached to reduce the overhead of repeated invocations. If the environment is
+removed, a new one will be created automatically.
When installing a tool with uv tool install, a virtual environment is created in the uv tools
+directory. The environment will not be removed unless the tool is uninstalled. If the environment is
+manually deleted, the tool will fail to run.
Unless a specific version is requested, uv tool install will install the latest available of the
+requested tool. uvx will use the latest available version of the requested tool on the first
+invocation. After that, uvx will use the cached version of the tool unless a different version is
+requested, the cache is pruned, or the cache is refreshed.
For example, to run a specific version of Ruff:
+ +A subsequent invocation of uvx will use the latest, not the cached, version.
But, if a new version of Ruff was released, it would not be used unless the cache was refreshed.
+To request the latest version of Ruff and refresh the cache, use the @latest suffix:
Once a tool is installed with uv tool install, uvx will use the installed version by default.
For example, after installing an older version of Ruff:
+ +The version of ruff and uvx ruff is the same:
However, you can ignore the installed version by requesting the latest version explicitly, e.g.:
+ +Or, by using the --isolated flag, which will avoid refreshing the cache but ignore the installed
+version:
uv tool install will also respect the {package}@{version} and {package}@latest specifiers, as
+in:
By default, the uv tools directory is named tools and is in the uv application state directory,
+e.g., ~/.local/share/uv/tools. The location may be customized with the UV_TOOL_DIR environment
+variable.
To display the path to the tool installation directory:
+ +Tool environments are placed in a directory with the same name as the tool package, e.g.,
+.../tools/<name>.
Important
+Tool environments are not intended to be mutated directly. It is strongly recommended never to
+mutate a tool environment manually, e.g., with a pip operation.
Tool environments may be upgraded via uv tool upgrade, or re-created entirely via subsequent
+uv tool install operations.
To upgrade all packages in a tool environment
+ +To upgrade a single package in a tool environment:
+ +Tool upgrades will respect the version constraints provided when installing the tool. For example,
+uv tool install black >=23,<24 followed by uv tool upgrade black will upgrade Black to the
+latest version in the range >=23,<24.
To instead replace the version constraints, reinstall the tool with uv tool install:
Similarly, tool upgrades will retain the settings provided when installing the tool. For example,
+uv tool install black --prerelease allow followed by uv tool upgrade black will retain the
+--prerelease allow setting.
Note
+Tool upgrades will reinstall the tool executables, even if they have not changed.
+To reinstall packages during upgrade, use the --reinstall and --reinstall-package options.
To reinstall all packages in a tool environment
+ +To reinstall a single package in a tool environment:
+ +Additional packages can be included during tool execution:
+ +And, during tool installation:
+ +The --with option can be provided multiple times to include additional packages.
The --with option supports package specifications, so a specific version can be requested:
The -w shorthand can be used in place of the --with option:
If the requested version conflicts with the requirements of the tool package, package resolution +will fail and the command will error.
+When installing a tool, you may want to include executables from additional packages in the same +tool environment. This is useful when you have related tools that work together or when you want to +install multiple executables that share dependencies.
+The --with-executables-from option allows you to specify additional packages whose executables
+should be installed alongside the main tool:
For example, to install Ansible along with executables from ansible-core and ansible-lint:
This will install all executables from the ansible, ansible-core, and ansible-lint packages
+into the same tool environment, making them all available on the PATH.
The --with-executables-from option can be combined with other installation options:
Note that --with-executables-from differs from --with in that:
--with includes additional packages as dependencies but does not install their executables--with-executables-from includes both the packages as dependencies and installs their
+ executablesEach tool environment is linked to a specific Python version. This uses the same Python version
+discovery logic as other virtual environments
+created by uv, but will ignore non-global Python version requests like .python-version files and
+the requires-python value from a pyproject.toml.
The --python option can be used to request a specific version. See the
+Python version documentation for more details.
If the Python version used by a tool is uninstalled, the tool environment will be broken and the +tool may be unusable.
+Tool executables include all console entry points, script entry points, and binary scripts provided
+by a Python package. Tool executables are symlinked into the bin directory on Unix and copied on
+Windows.
bin directoryExecutables are installed into the user bin directory following the XDG standard, e.g.,
+~/.local/bin. Unlike other directory schemes in uv, the XDG standard is used on all platforms
+notably including Windows and macOS — there is no clear alternative location to place executables on
+these platforms. The installation directory is determined from the first available environment
+variable:
$UV_TOOL_BIN_DIR$XDG_BIN_HOME$XDG_DATA_HOME/../bin$HOME/.local/binExecutables provided by dependencies of tool packages are not installed.
+PATHThe bin directory must be in the PATH variable for tool executables to be available from the
+shell. If it is not in the PATH, a warning will be displayed. The uv tool update-shell command
+can be used to add the bin directory to the PATH in common shell configuration files.
Installation of tools will not overwrite executables in the bin directory that were not previously
+installed by uv. For example, if pipx has been used to install a tool, uv tool install will
+fail. The --force flag can be used to override this behavior.
uv runThe invocation uv tool run <name> (or uvx <name>) is nearly equivalent to:
However, there are a couple notable differences when using uv's tool interface:
+--with option is not needed — the required package is inferred from the command name.--no-project flag is not needed — tools are always run isolated from the project.uv tool run will use the installed version but uv run will
+ not.If the tool should not be isolated from the project, e.g., when running pytest or mypy, then
+uv run should be used instead of uv tool run.
uv provides essential features for Python development — from installing Python and hacking on simple +scripts to working on large projects that support multiple Python versions and platforms.
+uv's interface can be broken down into sections, which are usable independently or together.
+Installing and managing Python itself.
+uv python install: Install Python versions.uv python list: View available Python versions.uv python find: Find an installed Python version.uv python pin: Pin the current project to use a specific Python version.uv python uninstall: Uninstall a Python version.See the guide on installing Python to get started.
+Executing standalone Python scripts, e.g., example.py.
uv run: Run a script.uv add --script: Add a dependency to a script.uv remove --script: Remove a dependency from a script.See the guide on running scripts to get started.
+Creating and working on Python projects, i.e., with a pyproject.toml.
uv init: Create a new Python project.uv add: Add a dependency to the project.uv remove: Remove a dependency from the project.uv sync: Sync the project's dependencies with the environment.uv lock: Create a lockfile for the project's dependencies.uv run: Run a command in the project environment.uv tree: View the dependency tree for the project.uv build: Build the project into distribution archives.uv publish: Publish the project to a package index.See the guide on projects to get started.
+Running and installing tools published to Python package indexes, e.g., ruff or black.
uvx / uv tool run: Run a tool in a temporary environment.uv tool install: Install a tool user-wide.uv tool uninstall: Uninstall a tool.uv tool list: List installed tools.uv tool update-shell: Update the shell to include tool executables.See the guide on tools to get started.
+Manually managing environments and packages — intended to be used in legacy workflows or cases where +the high-level commands do not provide enough control.
+Creating virtual environments (replacing venv and virtualenv):
uv venv: Create a new virtual environment.See the documentation on using environments for details.
+Managing packages in an environment (replacing pip and
+pipdeptree):
uv pip install: Install packages into the current environment.uv pip show: Show details about an installed package.uv pip freeze: List installed packages and their versions.uv pip check: Check that the current environment has compatible packages.uv pip list: List installed packages.uv pip uninstall: Uninstall packages.uv pip tree: View the dependency tree for the environment.See the documentation on managing packages for details.
+Locking packages in an environment (replacing pip-tools):
uv pip compile: Compile requirements into a lockfile.uv pip sync: Sync an environment with a lockfile.See the documentation on locking environments for details.
+Important
+These commands do not exactly implement the interfaces and behavior of the tools they are based on. The further you stray from common workflows, the more likely you are to encounter differences. Consult the pip-compatibility guide for details.
+Managing and inspecting uv's state, such as the cache, storage directories, or performing a +self-update:
+uv cache clean: Remove cache entries.uv cache prune: Remove outdated cache entries.uv cache dir: Show the uv cache directory path.uv tool dir: Show the uv tool directory path.uv python dir: Show the uv installed Python versions path.uv self update: Update uv to the latest version.Read the guides for an introduction to each feature, check out the +concept pages for in-depth details about uv's features, or learn how to +get help if you run into any problems.
+ + + + + + + + + + + + + + + + + +After installing uv, you can check that uv is available by running the uv
+command:
You should see a help menu listing the available commands.
+Now that you've confirmed uv is installed, check out an overview of features, learn +how to get help if you run into any problems, or jump to the +guides to start using uv.
+ + + + + + + + + + + + + + + + + +The --help flag can be used to view the help menu for a command, e.g., for uv:
To view the help menu for a specific command, e.g., for uv init:
When using the --help flag, uv displays a condensed help menu. To view a longer help menu for a
+command, use uv help:
To view the long help menu for a specific command, e.g., for uv init:
When using the long help menu, uv will attempt to use less or more to "page" the output so it is
+not all displayed at once. To exit the pager, press q.
The -v flag can be used to display verbose output for a command, e.g., for uv sync:
The -v flag can be repeated to increase verbosity, e.g.:
Often, the verbose output will include additional information about why uv is behaving in a certain +way.
+When seeking help, it's important to determine the version of uv that you're using — sometimes the +problem is already solved in a newer version.
+To check the installed version:
+ +The following are also valid:
+$ uv --version # Same output as `uv self version`
+$ uv -V # Will not include the build commit and date
+Note
+Before uv 0.7.0, uv version was used instead of uv self version.
The reference documentation contains a +troubleshooting guide for common issues.
+The issue tracker on GitHub is a good place to report bugs +and request features. Make sure to search for similar issues first, as it is common for someone else +to encounter the same problem.
+Astral has a Discord server, which is a great place to ask +questions, learn more about uv, and engage with other community members.
+ + + + + + + + + + + + + + + + + +To help you get started with uv, we'll cover a few important topics:
+ +Read on, or jump ahead to another section:
+ + + + + + + + + + + + + + + + + + +Install uv with our standalone installers or your package manager of choice.
+uv provides a standalone installer to download and install uv:
+Use curl to download the script and execute it with sh:
If your system doesn't have curl, you can use wget:
Request a specific version by including it in the URL:
+ +Use irm to download the script and execute it with iex:
Changing the execution policy allows running a script from the internet.
+Request a specific version by including it in the URL:
+ +Tip
+The installation script may be inspected before use:
+Alternatively, the installer or binaries can be downloaded directly from GitHub.
+See the reference documentation on the installer for details on +customizing your uv installation.
+For convenience, uv is published to PyPI.
+If installing from PyPI, we recommend installing uv into an isolated environment, e.g., with pipx:
However, pip can also be used:
Note
+uv ships with prebuilt distributions (wheels) for many platforms; if a wheel is not available for a given +platform, uv will be built from source, which requires a Rust toolchain. See the +contributing setup guide +for details on building uv from source.
+uv is available in the core Homebrew packages.
+ +uv is available via MacPorts.
+ +uv is available via WinGet.
+ +uv is available via Scoop.
+ +uv provides a Docker image at
+ghcr.io/astral-sh/uv.
See our guide on using uv in Docker for more details.
+uv release artifacts can be downloaded directly from +GitHub Releases.
+Each release page includes binaries for all supported platforms as well as instructions for using
+the standalone installer via github.com instead of astral.sh.
uv is available via Cargo, but must be built from Git rather than crates.io due +to its dependency on unpublished crates.
+ +Note
+This method builds uv from source, which requires a compatible Rust toolchain.
+When uv is installed via the standalone installer, it can update itself on-demand:
+ +Tip
+Updating uv will re-run the installer and can modify your shell profiles. To disable this
+behavior, set UV_NO_MODIFY_PATH=1.
When another installation method is used, self-updates are disabled. Use the package manager's
+upgrade method instead. For example, with pip:
Tip
+You can run echo $SHELL to help you determine your shell.
To enable shell autocompletion for uv commands, run one of the following:
+To enable shell autocompletion for uvx, run one of the following:
+Then restart the shell or source the shell config file.
+If you need to remove uv from your system, follow these steps:
+Clean up stored data (optional):
+ +Tip
+Before removing the binaries, you may want to remove any data that uv has stored.
+Remove the uv, uvx, and uvw binaries:
+Note
+Prior to 0.5.0, uv was installed into ~/.cargo/bin. The binaries can be removed from there to
+uninstall. Upgrading from an older version will not automatically remove the binaries from
+~/.cargo/bin.
See the first steps or jump straight to the guides to +start using uv.
+ + + + + + + + + + + + + + + + + +Check out one of the core guides to get started:
+Or, explore the concept documentation for comprehensive breakdown of each +feature.
+ + + + + + + + + + + + + + + + + +If Python is already installed on your system, uv will +detect and use it without configuration. However, uv can also +install and manage Python versions. uv automatically installs missing +Python versions as needed — you don't need to install Python to get started.
+To install the latest Python version:
+ +Note
+Python does not publish official distributable binaries. As such, uv uses distributions from the Astral python-build-standalone project. See the Python distributions documentation for more details.
Once Python is installed, it will be used by uv commands automatically. uv also adds the installed
+version to your PATH:
uv only installs a versioned executable by default. To install python and python3 executables,
+include the experimental --default option:
Tip
+See the documentation on installing Python executables +for more details.
+To install a specific Python version:
+ +To install multiple Python versions:
+ +To install an alternative Python implementation, e.g., PyPy:
+ +See the python install documentation
+for more details.
To reinstall uv-managed Python versions, use --reinstall, e.g.:
This will reinstall all previously installed Python versions. Improvements are constantly being +added to the Python distributions, so reinstalling may resolve bugs even if the Python version does +not change.
+To view available and installed Python versions:
+ +See the python list
+documentation for more details.
Python does not need to be explicitly installed to use uv. By default, uv will automatically +download Python versions when they are required. For example, the following would download Python +3.12 if it was not installed:
+ +Even if a specific Python version is not requested, uv will download the latest version on demand. +For example, if there are no Python versions on your system, the following will install Python +before creating a new virtual environment:
+ +Tip
+Automatic Python downloads can be easily disabled if you want more control over when Python is downloaded.
+uv will use existing Python installations if present on your system. There is no configuration +necessary for this behavior: uv will use the system Python if it satisfies the requirements of the +command invocation. See the +Python discovery documentation for +details.
+To force uv to use the system Python, provide the --no-managed-python flag. See the
+Python version preference
+documentation for more details.
Important
+Support for upgrading Python patch versions is in preview. This means the behavior is +experimental and subject to change.
+To upgrade a Python version to the latest supported patch release:
+ +To upgrade all uv-managed Python versions:
+ +See the python upgrade documentation
+for more details.
To learn more about uv python, see the Python version concept
+page and the command reference.
Or, read on to learn how to run scripts and invoke Python with uv.
+ + + + + + + + + + + + + + + + + + + + +While uv uses the official Python Package Index (PyPI) by default, it also supports +alternative package indexes. Most alternative indexes require various +forms of authentication, which require some initial setup.
+Important
+If using the pip interface, please read the documentation +on using multiple indexes +in uv — the default behavior is different from pip to prevent dependency confusion attacks, but +this means that uv may not find the versions of a package as you'd expect.
+uv can install packages from
+Azure Artifacts,
+either by using a
+Personal Access Token
+(PAT), or using the keyring package.
To use Azure Artifacts, add the index to your project:
+[[tool.uv.index]]
+name = "private-registry"
+url = "https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/simple/"
+If there is a personal access token (PAT) available (e.g.,
+$(System.AccessToken) in an Azure pipeline),
+credentials can be provided via "Basic" HTTP authentication scheme. Include the PAT in the password
+field of the URL. A username must be included as well, but can be any string.
For example, with the token stored in the $AZURE_ARTIFACTS_TOKEN environment variable, set
+credentials for the index with:
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=dummy
+export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$AZURE_ARTIFACTS_TOKEN"
+Note
+PRIVATE_REGISTRY should match the name of the index defined in your pyproject.toml.
keyring and artifacts-keyringYou can also authenticate to Artifacts using keyring package
+with the artifacts-keyring plugin. Because these
+two packages are required to authenticate to Azure Artifacts, they must be pre-installed from a
+source other than Artifacts.
The artifacts-keyring plugin wraps the
+Azure Artifacts Credential Provider tool. The
+credential provider supports a few different authentication modes including interactive login — see
+the tool's documentation for information on
+configuration.
uv only supports using the keyring package in
+subprocess mode. The keyring executable must be in
+the PATH, i.e., installed globally or in the active environment. The keyring CLI requires a
+username in the URL, and it must be VssSessionToken.
# Pre-install keyring and the Artifacts plugin from the public PyPI
+uv tool install keyring --with artifacts-keyring
+
+# Enable keyring authentication
+export UV_KEYRING_PROVIDER=subprocess
+
+# Set the username for the index
+export UV_INDEX_PRIVATE_REGISTRY_USERNAME=VssSessionToken
+Note
+The tool.uv.keyring-provider
+setting can be used to enable keyring in your uv.toml or pyproject.toml.
Similarly, the username for the index can be added directly to the index URL.
+If you also want to publish your own packages to Azure Artifacts, you can use uv publish as
+described in the Building and publishing guide.
First, add a publish-url to the index you want to publish packages to. For example:
[[tool.uv.index]]
+name = "private-registry"
+url = "https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/simple/"
+publish-url = "https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/upload/"
+Then, configure credentials (if not using keyring):
+ +And publish the package:
+ +To use uv publish without adding the publish-url to the project, you can set UV_PUBLISH_URL:
$ export UV_PUBLISH_URL=https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/upload/
+$ uv publish
+Note this method is not preferable because uv cannot check if the package is already published +before uploading artifacts.
+uv can install packages from
+Google Artifact Registry, either by using an
+access token, or using the keyring package.
Note
+This guide assumes that gcloud CLI is installed and
+authenticated.
To use Google Artifact Registry, add the index to your project:
+[[tool.uv.index]]
+name = "private-registry"
+url = "https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/simple/"
+Credentials can be provided via "Basic" HTTP authentication scheme. Include access token in the
+password field of the URL. Username must be oauth2accesstoken, otherwise authentication will fail.
Generate a token with gcloud:
Note
+You might need to pass extra parameters to properly generate the token (like --project), this
+is a basic example.
Then set credentials for the index with:
+export UV_INDEX_PRIVATE_REGISTRY_USERNAME=oauth2accesstoken
+export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$ARTIFACT_REGISTRY_TOKEN"
+Note
+PRIVATE_REGISTRY should match the name of the index defined in your pyproject.toml.
keyring and keyrings.google-artifactregistry-authYou can also authenticate to Artifact Registry using keyring
+package with the
+keyrings.google-artifactregistry-auth plugin.
+Because these two packages are required to authenticate to Artifact Registry, they must be
+pre-installed from a source other than Artifact Registry.
The keyrings.google-artifactregistry-auth plugin wraps
+gcloud CLI to generate short-lived access tokens, securely
+store them in system keyring, and refresh them when they are expired.
uv only supports using the keyring package in
+subprocess mode. The keyring executable must be in
+the PATH, i.e., installed globally or in the active environment. The keyring CLI requires a
+username in the URL and it must be oauth2accesstoken.
# Pre-install keyring and Artifact Registry plugin from the public PyPI
+uv tool install keyring --with keyrings.google-artifactregistry-auth
+
+# Enable keyring authentication
+export UV_KEYRING_PROVIDER=subprocess
+
+# Set the username for the index
+export UV_INDEX_PRIVATE_REGISTRY_USERNAME=oauth2accesstoken
+Note
+The tool.uv.keyring-provider
+setting can be used to enable keyring in your uv.toml or pyproject.toml.
Similarly, the username for the index can be added directly to the index URL.
+If you also want to publish your own packages to Google Artifact Registry, you can use uv publish
+as described in the Building and publishing guide.
First, add a publish-url to the index you want to publish packages to. For example:
[[tool.uv.index]]
+name = "private-registry"
+url = "https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/simple/"
+publish-url = "https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/"
+Then, configure credentials (if not using keyring):
+$ export UV_PUBLISH_USERNAME=oauth2accesstoken
+$ export UV_PUBLISH_PASSWORD="$ARTIFACT_REGISTRY_TOKEN"
+And publish the package:
+ +To use uv publish without adding the publish-url to the project, you can set UV_PUBLISH_URL:
Note this method is not preferable because uv cannot check if the package is already published +before uploading artifacts.
+uv can install packages from
+AWS CodeArtifact, either by
+using an access token, or using the keyring package.
Note
+This guide assumes that awscli is installed and authenticated.
The index can be declared like so:
+[[tool.uv.index]]
+name = "private-registry"
+url = "https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/simple/"
+Credentials can be provided via "Basic" HTTP authentication scheme. Include access token in the
+password field of the URL. Username must be aws, otherwise authentication will fail.
Generate a token with awscli:
export AWS_CODEARTIFACT_TOKEN="$(
+ aws codeartifact get-authorization-token \
+ --domain <DOMAIN> \
+ --domain-owner <ACCOUNT_ID> \
+ --query authorizationToken \
+ --output text
+)"
+Note
+You might need to pass extra parameters to properly generate the token (like --region), this
+is a basic example.
Then set credentials for the index with:
+export UV_INDEX_PRIVATE_REGISTRY_USERNAME=aws
+export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$AWS_CODEARTIFACT_TOKEN"
+Note
+PRIVATE_REGISTRY should match the name of the index defined in your pyproject.toml.
keyring and keyrings.codeartifactYou can also authenticate to Artifact Registry using keyring
+package with the keyrings.codeartifact plugin.
+Because these two packages are required to authenticate to Artifact Registry, they must be
+pre-installed from a source other than Artifact Registry.
The keyrings.codeartifact plugin wraps boto3 to generate
+short-lived access tokens, securely store them in system keyring, and refresh them when they are
+expired.
uv only supports using the keyring package in
+subprocess mode. The keyring executable must be in
+the PATH, i.e., installed globally or in the active environment. The keyring CLI requires a
+username in the URL and it must be aws.
# Pre-install keyring and AWS CodeArtifact plugin from the public PyPI
+uv tool install keyring --with keyrings.codeartifact
+
+# Enable keyring authentication
+export UV_KEYRING_PROVIDER=subprocess
+
+# Set the username for the index
+export UV_INDEX_PRIVATE_REGISTRY_USERNAME=aws
+Note
+The tool.uv.keyring-provider
+setting can be used to enable keyring in your uv.toml or pyproject.toml.
Similarly, the username for the index can be added directly to the index URL.
+If you also want to publish your own packages to AWS CodeArtifact, you can use uv publish as
+described in the Building and publishing guide.
First, add a publish-url to the index you want to publish packages to. For example:
[[tool.uv.index]]
+name = "private-registry"
+url = "https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/simple/"
+publish-url = "https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/"
+Then, configure credentials (if not using keyring):
+ +And publish the package:
+ +To use uv publish without adding the publish-url to the project, you can set UV_PUBLISH_URL:
$ export UV_PUBLISH_URL=https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/
+$ uv publish
+Note this method is not preferable because uv cannot check if the package is already published +before uploading artifacts.
+uv can install packages from JFrog Artifactory, either by using a username and password or a JWT +token.
+To use it, add the index to your project:
+[[tool.uv.index]]
+name = "private-registry"
+url = "https://<organization>.jfrog.io/artifactory/api/pypi/<repository>/simple"
+$ export UV_INDEX_PRIVATE_REGISTRY_USERNAME="<username>"
+$ export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="<password>"
+$ export UV_INDEX_PRIVATE_REGISTRY_USERNAME=""
+$ export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$JFROG_JWT_TOKEN"
+Note
+Replace PRIVATE_REGISTRY in the environment variable names with the actual index name defined in your pyproject.toml.
Add a publish-url to your index definition:
[[tool.uv.index]]
+name = "private-registry"
+url = "https://<organization>.jfrog.io/artifactory/api/pypi/<repository>/simple"
+publish-url = "https://<organization>.jfrog.io/artifactory/api/pypi/<repository>"
+Important
+If you use --token "$JFROG_TOKEN" or UV_PUBLISH_TOKEN with JFrog, you will receive a
+401 Unauthorized error as JFrog requires an empty username but uv passes __token__ for as
+the username when --token is used.
To authenticate, pass your token as the password and set the username to an empty string:
+ +Alternatively, you can set environment variables:
+$ export UV_PUBLISH_USERNAME=""
+$ export UV_PUBLISH_PASSWORD="$JFROG_TOKEN"
+$ uv publish --index private-registry
+Note
+The publish environment variables (UV_PUBLISH_USERNAME and UV_PUBLISH_PASSWORD) do not include the index name.
AWS Lambda is a serverless computing service that lets you run +code without provisioning or managing servers.
+You can use uv with AWS Lambda to manage your Python dependencies, build your deployment package, +and deploy your Lambda functions.
+Tip
+Check out the uv-aws-lambda-example project for
+an example of best practices when using uv to deploy an application to AWS Lambda.
To start, assume we have a minimal FastAPI application with the following structure:
+ +Where the pyproject.toml contains:
[project]
+name = "uv-aws-lambda-example"
+version = "0.1.0"
+requires-python = ">=3.13"
+dependencies = [
+ # FastAPI is a modern web framework for building APIs with Python.
+ "fastapi",
+ # Mangum is a library that adapts ASGI applications to AWS Lambda and API Gateway.
+ "mangum",
+]
+
+[dependency-groups]
+dev = [
+ # In development mode, include the FastAPI development server.
+ "fastapi[standard]>=0.115",
+]
+And the main.py file contains:
import logging
+
+from fastapi import FastAPI
+from mangum import Mangum
+
+logger = logging.getLogger()
+logger.setLevel(logging.INFO)
+
+app = FastAPI()
+handler = Mangum(app)
+
+
+@app.get("/")
+async def root() -> str:
+ return "Hello, world!"
+We can run this application locally with:
+ +From there, opening http://127.0.0.1:8000/ in a web browser will display "Hello, world!"
+To deploy to AWS Lambda, we need to build a container image that includes the application code and +dependencies in a single output directory.
+We'll follow the principles outlined in the Docker guide (in particular, a +multi-stage build) to ensure that the final image is as small and cache-friendly as possible.
+In the first stage, we'll populate a single directory with all application code and dependencies. In +the second stage, we'll copy this directory over to the final image, omitting the build tools and +other unnecessary files.
+FROM ghcr.io/astral-sh/uv:0.9.8 AS uv
+
+# First, bundle the dependencies into the task root.
+FROM public.ecr.aws/lambda/python:3.13 AS builder
+
+# Enable bytecode compilation, to improve cold-start performance.
+ENV UV_COMPILE_BYTECODE=1
+
+# Disable installer metadata, to create a deterministic layer.
+ENV UV_NO_INSTALLER_METADATA=1
+
+# Enable copy mode to support bind mount caching.
+ENV UV_LINK_MODE=copy
+
+# Bundle the dependencies into the Lambda task root via `uv pip install --target`.
+#
+# Omit any local packages (`--no-emit-workspace`) and development dependencies (`--no-dev`).
+# This ensures that the Docker layer cache is only invalidated when the `pyproject.toml` or `uv.lock`
+# files change, but remains robust to changes in the application code.
+RUN --mount=from=uv,source=/uv,target=/bin/uv \
+ --mount=type=cache,target=/root/.cache/uv \
+ --mount=type=bind,source=uv.lock,target=uv.lock \
+ --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+ uv export --frozen --no-emit-workspace --no-dev --no-editable -o requirements.txt && \
+ uv pip install -r requirements.txt --target "${LAMBDA_TASK_ROOT}"
+
+FROM public.ecr.aws/lambda/python:3.13
+
+# Copy the runtime dependencies from the builder stage.
+COPY --from=builder ${LAMBDA_TASK_ROOT} ${LAMBDA_TASK_ROOT}
+
+# Copy the application code.
+COPY ./app ${LAMBDA_TASK_ROOT}/app
+
+# Set the AWS Lambda handler.
+CMD ["app.main.handler"]
+Tip
+To deploy to ARM-based AWS Lambda runtimes, replace public.ecr.aws/lambda/python:3.13 with public.ecr.aws/lambda/python:3.13-arm64.
We can build the image with, e.g.:
+ +The core benefits of this Dockerfile structure are as follows:
+Concretely, rebuilding the image after modifying the application source code can reuse the cached +layers, resulting in millisecond builds:
+ => [internal] load build definition from Dockerfile 0.0s
+ => => transferring dockerfile: 1.31kB 0.0s
+ => [internal] load metadata for public.ecr.aws/lambda/python:3.13 0.3s
+ => [internal] load metadata for ghcr.io/astral-sh/uv:latest 0.3s
+ => [internal] load .dockerignore 0.0s
+ => => transferring context: 106B 0.0s
+ => [uv 1/1] FROM ghcr.io/astral-sh/uv:latest@sha256:ea61e006cfec0e8d81fae901ad703e09d2c6cf1aa58abcb6507d124b50286f 0.0s
+ => [builder 1/2] FROM public.ecr.aws/lambda/python:3.13@sha256:f5b51b377b80bd303fe8055084e2763336ea8920d12955b23ef 0.0s
+ => [internal] load build context 0.0s
+ => => transferring context: 185B 0.0s
+ => CACHED [builder 2/2] RUN --mount=from=uv,source=/uv,target=/bin/uv --mount=type=cache,target=/root/.cache/u 0.0s
+ => CACHED [stage-2 2/3] COPY --from=builder /var/task /var/task 0.0s
+ => CACHED [stage-2 3/3] COPY ./app /var/task 0.0s
+ => exporting to image 0.0s
+ => => exporting layers 0.0s
+ => => writing image sha256:6f8f9ef715a7cda466b677a9df4046ebbb90c8e88595242ade3b4771f547652d 0.0
+After building, we can push the image to +Elastic Container Registry (ECR) with, e.g.:
+$ aws ecr get-login-password --region region | docker login --username AWS --password-stdin aws_account_id.dkr.ecr.region.amazonaws.com
+$ docker tag fastapi-app:latest aws_account_id.dkr.ecr.region.amazonaws.com/fastapi-app:latest
+$ docker push aws_account_id.dkr.ecr.region.amazonaws.com/fastapi-app:latest
+Finally, we can deploy the image to AWS Lambda using the AWS Management Console or the AWS CLI, +e.g.:
+$ aws lambda create-function \
+ --function-name myFunction \
+ --package-type Image \
+ --code ImageUri=aws_account_id.dkr.ecr.region.amazonaws.com/fastapi-app:latest \
+ --role arn:aws:iam::111122223333:role/my-lambda-role
+Where the +execution role +is created via:
+$ aws iam create-role \
+ --role-name my-lambda-role \
+ --assume-role-policy-document '{"Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole"}]}'
+Or, update an existing function with:
+$ aws lambda update-function-code \
+ --function-name myFunction \
+ --image-uri aws_account_id.dkr.ecr.region.amazonaws.com/fastapi-app:latest \
+ --publish
+To test the Lambda, we can invoke it via the AWS Management Console or the AWS CLI, e.g.:
+$ aws lambda invoke \
+ --function-name myFunction \
+ --payload file://event.json \
+ --cli-binary-format raw-in-base64-out \
+ response.json
+{
+ "StatusCode": 200,
+ "ExecutedVersion": "$LATEST"
+}
+Where event.json contains the event payload to pass to the Lambda function:
And response.json contains the response from the Lambda function:
{
+ "statusCode": 200,
+ "headers": {
+ "content-length": "14",
+ "content-type": "application/json"
+ },
+ "multiValueHeaders": {},
+ "body": "\"Hello, world!\"",
+ "isBase64Encoded": false
+}
+For details, see the +AWS Lambda documentation.
+If a project includes local dependencies (e.g., via +Workspaces), those too must be included in the deployment +package.
+We'll start by extending the above example to include a dependency on a locally-developed library
+named library.
First, we'll create the library itself:
+ +Running uv init within the project directory will automatically convert project to a workspace
+and add library as a workspace member:
[project]
+name = "uv-aws-lambda-example"
+version = "0.1.0"
+requires-python = ">=3.13"
+dependencies = [
+ # FastAPI is a modern web framework for building APIs with Python.
+ "fastapi",
+ # A local library.
+ "library",
+ # Mangum is a library that adapts ASGI applications to AWS Lambda and API Gateway.
+ "mangum",
+]
+
+[dependency-groups]
+dev = [
+ # In development mode, include the FastAPI development server.
+ "fastapi[standard]",
+]
+
+[tool.uv.workspace]
+members = ["library"]
+
+[tool.uv.sources]
+lib = { workspace = true }
+By default, uv init --lib will create a package that exports a hello function. We'll modify the
+application source code to call that function:
import logging
+
+from fastapi import FastAPI
+from mangum import Mangum
+
+from library import hello
+
+logger = logging.getLogger()
+logger.setLevel(logging.INFO)
+
+app = FastAPI()
+handler = Mangum(app)
+
+
+@app.get("/")
+async def root() -> str:
+ return hello()
+We can run the modified application locally with:
+ +And confirm that opening http://127.0.0.1:8000/ in a web browser displays, "Hello from library!" +(instead of "Hello, World!")
+Finally, we'll update the Dockerfile to include the local library in the deployment package:
+FROM ghcr.io/astral-sh/uv:0.9.8 AS uv
+
+# First, bundle the dependencies into the task root.
+FROM public.ecr.aws/lambda/python:3.13 AS builder
+
+# Enable bytecode compilation, to improve cold-start performance.
+ENV UV_COMPILE_BYTECODE=1
+
+# Disable installer metadata, to create a deterministic layer.
+ENV UV_NO_INSTALLER_METADATA=1
+
+# Enable copy mode to support bind mount caching.
+ENV UV_LINK_MODE=copy
+
+# Bundle the dependencies into the Lambda task root via `uv pip install --target`.
+#
+# Omit any local packages (`--no-emit-workspace`) and development dependencies (`--no-dev`).
+# This ensures that the Docker layer cache is only invalidated when the `pyproject.toml` or `uv.lock`
+# files change, but remains robust to changes in the application code.
+RUN --mount=from=uv,source=/uv,target=/bin/uv \
+ --mount=type=cache,target=/root/.cache/uv \
+ --mount=type=bind,source=uv.lock,target=uv.lock \
+ --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+ uv export --frozen --no-emit-workspace --no-dev --no-editable -o requirements.txt && \
+ uv pip install -r requirements.txt --target "${LAMBDA_TASK_ROOT}"
+
+# If you have a workspace, copy it over and install it too.
+#
+# By omitting `--no-emit-workspace`, `library` will be copied into the task root. Using a separate
+# `RUN` command ensures that all third-party dependencies are cached separately and remain
+# robust to changes in the workspace.
+RUN --mount=from=uv,source=/uv,target=/bin/uv \
+ --mount=type=cache,target=/root/.cache/uv \
+ --mount=type=bind,source=uv.lock,target=uv.lock \
+ --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+ --mount=type=bind,source=library,target=library \
+ uv export --frozen --no-dev --no-editable -o requirements.txt && \
+ uv pip install -r requirements.txt --target "${LAMBDA_TASK_ROOT}"
+
+FROM public.ecr.aws/lambda/python:3.13
+
+# Copy the runtime dependencies from the builder stage.
+COPY --from=builder ${LAMBDA_TASK_ROOT} ${LAMBDA_TASK_ROOT}
+
+# Copy the application code.
+COPY ./app ${LAMBDA_TASK_ROOT}/app
+
+# Set the AWS Lambda handler.
+CMD ["app.main.handler"]
+Tip
+To deploy to ARM-based AWS Lambda runtimes, replace public.ecr.aws/lambda/python:3.13 with public.ecr.aws/lambda/python:3.13-arm64.
From there, we can build and deploy the updated image as before.
+AWS Lambda also supports deployment via zip archives. For simple applications, zip archives can be a +more straightforward and efficient deployment method than Docker images; however, zip archives are +limited to +250 MB +in size.
+Returning to the FastAPI example, we can bundle the application dependencies into a local directory +for AWS Lambda via:
+$ uv export --frozen --no-dev --no-editable -o requirements.txt
+$ uv pip install \
+ --no-installer-metadata \
+ --no-compile-bytecode \
+ --python-platform x86_64-manylinux2014 \
+ --python 3.13 \
+ --target packages \
+ -r requirements.txt
+Tip
+To deploy to ARM-based AWS Lambda runtimes, replace x86_64-manylinux2014 with aarch64-manylinux2014.
Following the +AWS Lambda documentation, we can +then bundle these dependencies into a zip as follows:
+ +Finally, we can add the application code to the zip archive:
+ +We can then deploy the zip archive to AWS Lambda via the AWS Management Console or the AWS CLI, +e.g.:
+$ aws lambda create-function \
+ --function-name myFunction \
+ --runtime python3.13 \
+ --zip-file fileb://package.zip \
+ --handler app.main.handler \
+ --role arn:aws:iam::111122223333:role/service-role/my-lambda-role
+Where the +execution role +is created via:
+$ aws iam create-role \
+ --role-name my-lambda-role \
+ --assume-role-policy-document '{"Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole"}]}'
+Or, update an existing function with:
+$ aws lambda update-function-code \
+ --function-name myFunction \
+ --zip-file fileb://package.zip
+Note
+By default, the AWS Management Console assumes a Lambda entrypoint of lambda_function.lambda_handler.
+If your application uses a different entrypoint, you'll need to modify it in the AWS Management Console.
+For example, the above FastAPI application uses app.main.handler.
To test the Lambda, we can invoke it via the AWS Management Console or the AWS CLI, e.g.:
+$ aws lambda invoke \
+ --function-name myFunction \
+ --payload file://event.json \
+ --cli-binary-format raw-in-base64-out \
+ response.json
+{
+ "StatusCode": 200,
+ "ExecutedVersion": "$LATEST"
+}
+Where event.json contains the event payload to pass to the Lambda function:
And response.json contains the response from the Lambda function:
{
+ "statusCode": 200,
+ "headers": {
+ "content-length": "14",
+ "content-type": "application/json"
+ },
+ "multiValueHeaders": {},
+ "body": "\"Hello, world!\"",
+ "isBase64Encoded": false
+}
+AWS Lambda also supports the deployment of multiple composed +Lambda layers when working with +zip archives. These layers are conceptually similar to layers in a Docker image, allowing you to +separate application code from dependencies.
+In particular, we can create a lambda layer for application dependencies and attach it to the Lambda +function, separate from the application code itself. This setup can improve cold-start performance +for application updates, as the dependencies layer can be reused across deployments.
+To create a Lambda layer, we'll follow similar steps, but create two separate zip archives: one for +the application code and one for the application dependencies.
+First, we'll create the dependency layer. Lambda layers are expected to follow a slightly different
+structure, so we'll use --prefix rather than --target:
$ uv export --frozen --no-dev --no-editable -o requirements.txt
+$ uv pip install \
+ --no-installer-metadata \
+ --no-compile-bytecode \
+ --python-platform x86_64-manylinux2014 \
+ --python 3.13 \
+ --prefix packages \
+ -r requirements.txt
+We'll then zip the dependencies in adherence with the expected layout for Lambda layers:
+ +Tip
+To generate deterministic zip archives, consider passing the -X flag to zip to exclude
+extended attributes and file system metadata.
And publish the Lambda layer:
+$ aws lambda publish-layer-version --layer-name dependencies-layer \
+ --zip-file fileb://layer_content.zip \
+ --compatible-runtimes python3.13 \
+ --compatible-architectures "x86_64"
+We can then create the Lambda function as in the previous example, omitting the dependencies:
+$ # Zip the application code.
+$ zip -r app.zip app
+
+$ # Create the Lambda function.
+$ aws lambda create-function \
+ --function-name myFunction \
+ --runtime python3.13 \
+ --zip-file fileb://app.zip \
+ --handler app.main.handler \
+ --role arn:aws:iam::111122223333:role/service-role/my-lambda-role
+Finally, we can attach the dependencies layer to the Lambda function, using the ARN returned by the
+publish-layer-version step:
$ aws lambda update-function-configuration --function-name myFunction \
+ --cli-binary-format raw-in-base64-out \
+ --layers "arn:aws:lambda:region:111122223333:layer:dependencies-layer:1"
+When the application dependencies change, the layer can be updated independently of the application +by republishing the layer and updating the Lambda function configuration:
+$ # Update the dependencies in the layer.
+$ aws lambda publish-layer-version --layer-name dependencies-layer \
+ --zip-file fileb://layer_content.zip \
+ --compatible-runtimes python3.13 \
+ --compatible-architectures "x86_64"
+
+$ # Update the Lambda function configuration.
+$ aws lambda update-function-configuration --function-name myFunction \
+ --cli-binary-format raw-in-base64-out \
+ --layers "arn:aws:lambda:region:111122223333:layer:dependencies-layer:2"
+Coiled is a serverless, UX-focused cloud computing platform +that makes it easy to run code on cloud hardware (AWS, GCP, and Azure).
+This guide shows how to run Python scripts on the cloud using uv for dependency management and +Coiled for cloud deployment.
+Note
+We'll use this concrete example throughout this guide, but any Python script can be used with +uv and Coiled.
+We'll use the following script as an example:
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# "pandas",
+# "pyarrow",
+# "s3fs",
+# ]
+# ///
+
+import pandas as pd
+
+df = pd.read_parquet(
+ "s3://coiled-data/uber/part.0.parquet",
+ storage_options={"anon": True},
+)
+print(df.head())
+The script uses pandas to load a Parquet file hosted in a
+public bucket on S3, then prints the first few rows. It uses
+inline script metadata to enumerate its dependencies.
When running this script locally, e.g., with:
+ +uv will automatically create a virtual environment and installs its dependencies.
+To learn more about using inline script metadata with uv, see the +script guide.
+Using inline script metadata makes the script fully self-contained: it includes the information that +is needed to run it. This makes it easier to run on other machines, like a machine in the cloud.
+There are many use cases where resources beyond what's available on a local workstation are needed, +e.g.:
+Coiled makes it simple to run code on cloud hardware.
+First, authenticate with Coiled using
+coiled login :
You'll be prompted to create a Coiled account if you don't already have one — it's free to start +using Coiled.
+To instruct Coiled to run the script on a virtual machine on AWS, add two comments to the top:
+# COILED container ghcr.io/astral-sh/uv:debian-slim
+# COILED region us-east-2
+
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# "pandas",
+# "pyarrow",
+# "s3fs",
+# ]
+# ///
+
+import pandas as pd
+
+df = pd.read_parquet(
+ "s3://coiled-data/uber/part.0.parquet",
+ storage_options={"anon": True},
+)
+print(df.head())
+Tip
+While Coiled supports AWS, GCP, and Azure, this example assumes AWS is being used
+(see the region option above). If you're new to Coiled, you'll automatically have
+access to a free account running on AWS. If you're not running on AWS, you can either use
+a valid region for your cloud provider or remove the region line above.
The comments tell Coiled to use the official uv Docker image when
+running the script (ensuring uv is available) and to run in the us-east-2 region on AWS (where
+this example data file happens to live) to avoid any data egress.
To submit a batch job for Coiled to run, use
+coiled batch run
+to execute the uv run command in the cloud:
The same process that previously ran locally is now running on a remote cloud VM on AWS.
+You can monitor the progress of the batch job in the UI at
+cloud.coiled.io or from the terminal using the coiled batch status,
+coiled batch wait, and coiled batch logs commands.
Note there's additional configuration we could have specified, e.g., the instance type (the default +is a 4-core virtual machine with 16 GiB of memory), disk size, whether to use spot instance, and +more. See the +Coiled Batch documentation for +more details.
+For more details on Coiled, and how it can help with other use cases, see the +Coiled documentation.
+ + + + + + + + + + + + + + + + + + + + +It is considered best practice to regularly update dependencies, to avoid being exposed to +vulnerabilities, limit incompatibilities between dependencies, and avoid complex upgrades when +upgrading from a too old version. A variety of tools can help staying up-to-date by creating +automated pull requests. Several of them support uv, or have work underway to support it.
+uv is supported by Renovate.
+uv.lock outputRenovate uses the presence of a uv.lock file to determine that uv is used for managing
+dependencies, and will suggest upgrades to
+project dependencies,
+optional dependencies and
+development dependencies.
+Renovate will update both the pyproject.toml and uv.lock files.
The lockfile can also be refreshed on a regular basis (for instance to update transitive
+dependencies) by enabling the
+lockFileMaintenance
+option:
{
+ $schema: "https://docs.renovatebot.com/renovate-schema.json",
+ lockFileMaintenance: {
+ enabled: true,
+ },
+}
+Renovate supports updating dependencies defined using +script inline metadata.
+Since it cannot automatically detect which Python files use script inline metadata, their locations
+need to be explicitly defined using
+fileMatch, like so:
{
+ $schema: "https://docs.renovatebot.com/renovate-schema.json",
+ pep723: {
+ fileMatch: [
+ "scripts/generate_docs\\.py",
+ "scripts/run_server\\.py",
+ ],
+ },
+}
+Dependabot has announced support for uv, but there are some use cases that are not yet working. See +astral-sh/uv#2512 for updates.
+Dependabot supports updating uv.lock files. To enable it, add the uv package-ecosystem to your
+updates list in the dependabot.yml:
Tip
+Check out the uv-docker-example project for
+an example of best practices when using uv to build an application in Docker.
uv provides both distroless Docker images, which are useful for +copying uv binaries into your own image builds, and images derived from popular +base images, which are useful for using uv in a container. The distroless images do not contain +anything but the uv binaries. In contrast, the derived images include an operating system with uv +pre-installed.
+As an example, to run uv in a container using a Debian-based image:
+ +The following distroless images are available:
+ghcr.io/astral-sh/uv:latestghcr.io/astral-sh/uv:{major}.{minor}.{patch}, e.g., ghcr.io/astral-sh/uv:0.9.8ghcr.io/astral-sh/uv:{major}.{minor}, e.g., ghcr.io/astral-sh/uv:0.8 (the latest patch
+ version)And the following derived images are available:
+ +alpine:3.22:ghcr.io/astral-sh/uv:alpineghcr.io/astral-sh/uv:alpine3.22alpine:3.21:ghcr.io/astral-sh/uv:alpine3.21debian:trixie-slim:ghcr.io/astral-sh/uv:debian-slimghcr.io/astral-sh/uv:trixie-slimdebian:bookworm-slim:ghcr.io/astral-sh/uv:bookworm-slimbuildpack-deps:trixie:ghcr.io/astral-sh/uv:debianghcr.io/astral-sh/uv:trixiebuildpack-deps:bookworm:ghcr.io/astral-sh/uv:bookwormpython3.x-alpine:ghcr.io/astral-sh/uv:python3.14-alpineghcr.io/astral-sh/uv:python3.13-alpineghcr.io/astral-sh/uv:python3.12-alpineghcr.io/astral-sh/uv:python3.11-alpineghcr.io/astral-sh/uv:python3.10-alpineghcr.io/astral-sh/uv:python3.9-alpineghcr.io/astral-sh/uv:python3.8-alpinepython3.x-trixie:ghcr.io/astral-sh/uv:python3.14-trixieghcr.io/astral-sh/uv:python3.13-trixieghcr.io/astral-sh/uv:python3.12-trixieghcr.io/astral-sh/uv:python3.11-trixieghcr.io/astral-sh/uv:python3.10-trixieghcr.io/astral-sh/uv:python3.9-trixiepython3.x-slim-trixie:ghcr.io/astral-sh/uv:python3.14-trixie-slimghcr.io/astral-sh/uv:python3.13-trixie-slimghcr.io/astral-sh/uv:python3.12-trixie-slimghcr.io/astral-sh/uv:python3.11-trixie-slimghcr.io/astral-sh/uv:python3.10-trixie-slimghcr.io/astral-sh/uv:python3.9-trixie-slimpython3.x-bookworm:ghcr.io/astral-sh/uv:python3.14-bookwormghcr.io/astral-sh/uv:python3.13-bookwormghcr.io/astral-sh/uv:python3.12-bookwormghcr.io/astral-sh/uv:python3.11-bookwormghcr.io/astral-sh/uv:python3.10-bookwormghcr.io/astral-sh/uv:python3.9-bookwormghcr.io/astral-sh/uv:python3.8-bookwormpython3.x-slim-bookworm:ghcr.io/astral-sh/uv:python3.14-bookworm-slimghcr.io/astral-sh/uv:python3.13-bookworm-slimghcr.io/astral-sh/uv:python3.12-bookworm-slimghcr.io/astral-sh/uv:python3.11-bookworm-slimghcr.io/astral-sh/uv:python3.10-bookworm-slimghcr.io/astral-sh/uv:python3.9-bookworm-slimghcr.io/astral-sh/uv:python3.8-bookworm-slimAs with the distroless image, each derived image is published with uv version tags as
+ghcr.io/astral-sh/uv:{major}.{minor}.{patch}-{base} and
+ghcr.io/astral-sh/uv:{major}.{minor}-{base}, e.g., ghcr.io/astral-sh/uv:0.9.8-alpine.
In addition, starting with 0.8 each derived image also sets UV_TOOL_BIN_DIR to /usr/local/bin
+to allow uv tool install to work as expected with the default user.
For more details, see the GitHub Container +page.
+Use one of the above images with uv pre-installed or install uv by copying the binary from the +official distroless Docker image:
+ +Or, with the installer:
+FROM python:3.12-slim-trixie
+
+# The installer requires curl (and certificates) to download the release archive
+RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates
+
+# Download the latest installer
+ADD https://astral.sh/uv/install.sh /uv-installer.sh
+
+# Run the installer then remove it
+RUN sh /uv-installer.sh && rm /uv-installer.sh
+
+# Ensure the installed binary is on the `PATH`
+ENV PATH="/root/.local/bin/:$PATH"
+Note this requires curl to be available.
In either case, it is best practice to pin to a specific uv version, e.g., with:
+ +Tip
+While the Dockerfile example above pins to a specific tag, it's also +possible to pin a specific SHA256. Pinning a specific SHA256 is considered +best practice in environments that require reproducible builds as tags can +be moved across different commit SHAs.
+ +Or, with the installer:
+ +If you're using uv to manage your project, you can copy it into the image and install it:
+# Copy the project into the image
+ADD . /app
+
+# Sync the project into a new environment, asserting the lockfile is up to date
+WORKDIR /app
+RUN uv sync --locked
+Important
+It is best practice to add .venv to a .dockerignore file
+in your repository to prevent it from being included in image builds. The project virtual
+environment is dependent on your local platform and should be created from scratch in the image.
Then, to start your application by default:
+# Presuming there is a `my_app` command provided by the project
+CMD ["uv", "run", "my_app"]
+Tip
+It is best practice to use intermediate layers separating installation +of dependencies and the project itself to improve Docker image build times.
+See a complete example in the
+uv-docker-example project.
Once the project is installed, you can either activate the project virtual environment by placing +its binary directory at the front of the path:
+ +Or, you can use uv run for any commands that require the environment:
Tip
+Alternatively, the
+UV_PROJECT_ENVIRONMENT setting can
+be set before syncing to install to the system Python environment and skip environment activation
+entirely.
To use installed tools, ensure the tool bin directory +is on the path:
+ +$ docker run -it $(docker build -q .) /bin/bash -c "cowsay -t hello"
+ _____
+| hello |
+ =====
+ \
+ \
+ ^__^
+ (oo)\_______
+ (__)\ )\/\
+ ||----w |
+ || ||
+Note
+The tool bin directory's location can be determined by running the uv tool dir --bin command
+in the container.
Alternatively, it can be set to a constant location:
+ +While uv will attempt to install a compatible Python version if no such +version is available in the image, uv does not yet support installing Python for musl Linux on ARM. +For example, if you are using an Alpine Linux base image on an ARM machine, you may need to add it +with the system package manager:
+ +When developing, it's useful to mount the project directory into a container. With this setup,
+changes to the project can be immediately reflected in a containerized service without rebuilding
+the image. However, it is important not to include the project virtual environment (.venv) in
+the mount, because the virtual environment is platform specific and the one built for the image
+should be kept.
docker runBind mount the project (in the working directory) to /app while retaining the .venv directory
+with an anonymous volume:
Tip
+The --rm flag is included to ensure the container and anonymous volume are cleaned up when the
+container exits.
See a complete example in the
+uv-docker-example project.
watch with docker composeWhen using Docker compose, more sophisticated tooling is available for container development. The
+watch option
+allows for greater granularity than is practical with a bind mount and supports triggering updates
+to the containerized service when files change.
Note
+This feature requires Compose 2.22.0 which is bundled with Docker Desktop 4.24.
+Configure watch in your
+Docker compose file
+to mount the project directory without syncing the project virtual environment and to rebuild the
+image when the configuration changes:
services:
+ example:
+ build: .
+
+ # ...
+
+ develop:
+ # Create a `watch` configuration to update the app
+ #
+ watch:
+ # Sync the working directory with the `/app` directory in the container
+ - action: sync
+ path: .
+ target: /app
+ # Exclude the project virtual environment
+ ignore:
+ - .venv/
+
+ # Rebuild the image on changes to the `pyproject.toml`
+ - action: rebuild
+ path: ./pyproject.toml
+Then, run docker compose watch to run the container with the development setup.
See a complete example in the
+uv-docker-example project.
Compiling Python source files to bytecode is typically desirable for production images as it tends +to improve startup time (at the cost of increased installation time).
+To enable bytecode compilation, use the --compile-bytecode flag:
Alternatively, you can set the UV_COMPILE_BYTECODE environment variable to ensure that all
+commands within the Dockerfile compile bytecode:
A cache mount can be used to +improve performance across builds:
+ +Changing the default UV_LINK_MODE silences warnings about
+not being able to use hard links since the cache and sync target are on separate file systems.
If you're not mounting the cache, image size can be reduced by using the --no-cache flag or
+setting UV_NO_CACHE.
By default, managed Python installations are not cached before being installed. Setting
+UV_PYTHON_CACHE_DIR can be used in combination with a cache mount:
ENV UV_PYTHON_CACHE_DIR=/root/.cache/uv/python
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv python install
+Note
+The cache directory's location can be determined by running the uv cache dir command in the
+container.
Alternatively, the cache can be set to a constant location:
+ +If you're using uv to manage your project, you can improve build times by moving your transitive
+dependency installation into its own layer via the --no-install options.
uv sync --no-install-project will install the dependencies of the project but not the project
+itself. Since the project changes frequently, but its dependencies are generally static, this can be
+a big time saver.
# Install uv
+FROM python:3.12-slim
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Change the working directory to the `app` directory
+WORKDIR /app
+
+# Install dependencies
+RUN --mount=type=cache,target=/root/.cache/uv \
+ --mount=type=bind,source=uv.lock,target=uv.lock \
+ --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+ uv sync --locked --no-install-project
+
+# Copy the project into the image
+ADD . /app
+
+# Sync the project
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --locked
+Note that the pyproject.toml is required to identify the project root and name, but the project
+contents are not copied into the image until the final uv sync command.
Tip
+If you're using a workspace, then use the
+--no-install-workspace flag which excludes the project and any workspace members.
If you want to remove specific packages from the sync, use --no-install-package <name>.
By default, uv installs projects and workspace members in editable mode, such that changes to the +source code are immediately reflected in the environment.
+uv sync and uv run both accept a --no-editable flag, which instructs uv to install the project
+in non-editable mode, removing any dependency on the source code.
In the context of a multi-stage Docker image, --no-editable can be used to include the project in
+the synced virtual environment from one stage, then copy the virtual environment alone (and not the
+source code) into the final image.
For example:
+# Install uv
+FROM python:3.12-slim AS builder
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Change the working directory to the `app` directory
+WORKDIR /app
+
+# Install dependencies
+RUN --mount=type=cache,target=/root/.cache/uv \
+ --mount=type=bind,source=uv.lock,target=uv.lock \
+ --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+ uv sync --locked --no-install-project --no-editable
+
+# Copy the project into the intermediate image
+ADD . /app
+
+# Sync the project
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --locked --no-editable
+
+FROM python:3.12-slim
+
+# Copy the environment, but not the source code
+COPY --from=builder --chown=app:app /app/.venv /app/.venv
+
+# Run the application
+CMD ["/app/.venv/bin/hello"]
+If uv isn't needed in the final image, the binary can be mounted in each invocation:
+ +The system Python environment is safe to use this context, since a container is already isolated.
+The --system flag can be used to install in the system environment:
To use the system Python environment by default, set the UV_SYSTEM_PYTHON variable:
Alternatively, a virtual environment can be created and activated:
+RUN uv venv /opt/venv
+# Use the virtual environment automatically
+ENV VIRTUAL_ENV=/opt/venv
+# Place entry points in the environment at the front of the path
+ENV PATH="/opt/venv/bin:$PATH"
+When using a virtual environment, the --system flag should be omitted from uv invocations:
To install requirements files, copy them into the container:
+ +When installing a project alongside requirements, it is best practice to separate copying the +requirements from the rest of the source code. This allows the dependencies of the project (which do +not change often) to be cached separately from the project itself (which changes very frequently).
+COPY pyproject.toml .
+RUN uv pip install -r pyproject.toml
+COPY . .
+RUN uv pip install -e .
+The Docker images are signed during the build process to provide proof of their origin. These +attestations can be used to verify that an image was produced from an official channel.
+For example, you can verify the attestations with the
+GitHub CLI tool gh:
$ gh attestation verify --owner astral-sh oci://ghcr.io/astral-sh/uv:latest
+Loaded digest sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx for oci://ghcr.io/astral-sh/uv:latest
+Loaded 1 attestation from GitHub API
+
+The following policy criteria will be enforced:
+- OIDC Issuer must match:................... https://token.actions.githubusercontent.com
+- Source Repository Owner URI must match:... https://github.com/astral-sh
+- Predicate type must match:................ https://slsa.dev/provenance/v1
+- Subject Alternative Name must match regex: (?i)^https://github.com/astral-sh/
+
+✓ Verification succeeded!
+
+sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx was attested by:
+REPO PREDICATE_TYPE WORKFLOW
+astral-sh/uv https://slsa.dev/provenance/v1 .github/workflows/build-docker.yml@refs/heads/main
+This tells you that the specific Docker image was built by the official uv GitHub release workflow +and hasn't been tampered with since.
+GitHub attestations build on the sigstore.dev infrastructure. As such
+you can also use the cosign command to verify the
+attestation blob against the (multi-platform) manifest for uv:
$ REPO=astral-sh/uv
+$ gh attestation download --repo $REPO oci://ghcr.io/${REPO}:latest
+Wrote attestations to file sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.jsonl.
+Any previous content has been overwritten
+
+The trusted metadata is now available at sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.jsonl
+$ docker buildx imagetools inspect ghcr.io/${REPO}:latest --format "{{json .Manifest}}" > manifest.json
+$ cosign verify-blob-attestation \
+ --new-bundle-format \
+ --bundle "$(jq -r .digest manifest.json).jsonl" \
+ --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
+ --certificate-identity-regexp="^https://github\.com/${REPO}/.*" \
+ <(jq -j '.|del(.digest,.size)' manifest.json)
+Verified OK
+Tip
+These examples use latest, but best practice is to verify the attestation for a specific
+version tag, e.g., ghcr.io/astral-sh/uv:0.9.8, or (even better) the specific image digest,
+such as ghcr.io/astral-sh/uv:0.5.27@sha256:5adf09a5a526f380237408032a9308000d14d5947eafa687ad6c6a2476787b4f.
FastAPI is a modern, high-performance Python web framework. +You can use uv to manage your FastAPI project, including installing dependencies, managing +environments, running FastAPI applications, and more.
+Note
+You can view the source code for this guide in the uv-fastapi-example repository.
+As an example, consider the sample application defined in the +FastAPI documentation, structured as +follows:
+project
+└── app
+ ├── __init__.py
+ ├── main.py
+ ├── dependencies.py
+ ├── routers
+ │ ├── __init__.py
+ │ ├── items.py
+ │ └── users.py
+ └── internal
+ ├── __init__.py
+ └── admin.py
+To use uv with this application, inside the project directory run:
This creates a project with an application layout
+and a pyproject.toml file.
Then, add a dependency on FastAPI:
+ +You should now have the following structure:
+project
+├── pyproject.toml
+└── app
+ ├── __init__.py
+ ├── main.py
+ ├── dependencies.py
+ ├── routers
+ │ ├── __init__.py
+ │ ├── items.py
+ │ └── users.py
+ └── internal
+ ├── __init__.py
+ └── admin.py
+And the contents of the pyproject.toml file should look something like this:
[project]
+name = "uv-fastapi-example"
+version = "0.1.0"
+description = "FastAPI project"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+ "fastapi[standard]",
+]
+From there, you can run the FastAPI application with:
+ +uv run will automatically resolve and lock the project dependencies (i.e., create a uv.lock
+alongside the pyproject.toml), create a virtual environment, and run the command in that
+environment.
Test the app by opening http://127.0.0.1:8000/?token=jessica in a web browser.
+To deploy the FastAPI application with Docker, you can use the following Dockerfile:
FROM python:3.12-slim
+
+# Install uv.
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Copy the application into the container.
+COPY . /app
+
+# Install the application dependencies.
+WORKDIR /app
+RUN uv sync --frozen --no-cache
+
+# Run the application.
+CMD ["/app/.venv/bin/fastapi", "run", "app/main.py", "--port", "80", "--host", "0.0.0.0"]
+Build the Docker image with:
+ +Run the Docker container locally with:
+ +Navigate to http://127.0.0.1:8000/?token=jessica in your browser to verify that the app is running +correctly.
+Tip
+For more on using uv with Docker, see the Docker guide.
+For use with GitHub Actions, we recommend the official
+astral-sh/setup-uv action, which installs uv, adds it to
+PATH, (optionally) persists the cache, and more, with support for all uv-supported platforms.
To install the latest version of uv:
+name: Example
+
+jobs:
+ uv-example:
+ name: python
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v5
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v6
+It is considered best practice to pin to a specific uv version, e.g., with:
+name: Example
+
+jobs:
+ uv-example:
+ name: python
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v5
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v6
+ with:
+ # Install a specific version of uv.
+ version: "0.9.8"
+Python can be installed with the python install command:
name: Example
+
+jobs:
+ uv-example:
+ name: python
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v5
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v6
+
+ - name: Set up Python
+ run: uv python install
+This will respect the Python version pinned in the project.
+Alternatively, the official GitHub setup-python action can be used. This can be faster, because
+GitHub caches the Python versions alongside the runner.
Set the
+python-version-file
+option to use the pinned version for the project:
name: Example
+
+jobs:
+ uv-example:
+ name: python
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v5
+
+ - name: "Set up Python"
+ uses: actions/setup-python@v6
+ with:
+ python-version-file: ".python-version"
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v6
+Or, specify the pyproject.toml file to ignore the pin and use the latest version compatible with
+the project's requires-python constraint:
name: Example
+
+jobs:
+ uv-example:
+ name: python
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v5
+
+ - name: "Set up Python"
+ uses: actions/setup-python@v6
+ with:
+ python-version-file: "pyproject.toml"
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v6
+When using a matrix to test multiple Python versions, set the Python version using
+astral-sh/setup-uv, which will override the Python version specification in the pyproject.toml
+or .python-version files:
jobs:
+ build:
+ name: continuous-integration
+ runs-on: ubuntu-latest
+ strategy:
+ matrix:
+ python-version:
+ - "3.10"
+ - "3.11"
+ - "3.12"
+
+ steps:
+ - uses: actions/checkout@v5
+
+ - name: Install uv and set the Python version
+ uses: astral-sh/setup-uv@v6
+ with:
+ python-version: ${{ matrix.python-version }}
+If not using the setup-uv action, you can set the UV_PYTHON environment variable:
jobs:
+ build:
+ name: continuous-integration
+ runs-on: ubuntu-latest
+ strategy:
+ matrix:
+ python-version:
+ - "3.10"
+ - "3.11"
+ - "3.12"
+ env:
+ UV_PYTHON: ${{ matrix.python-version }}
+ steps:
+ - uses: actions/checkout@v5
+Once uv and Python are installed, the project can be installed with uv sync and commands can be
+run in the environment with uv run:
name: Example
+
+jobs:
+ uv-example:
+ name: python
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v5
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v6
+
+ - name: Install the project
+ run: uv sync --locked --all-extras --dev
+
+ - name: Run tests
+ # For example, using `pytest`
+ run: uv run pytest tests
+Tip
+The
+UV_PROJECT_ENVIRONMENT setting can
+be used to install to the system Python environment instead of creating a virtual environment.
It may improve CI times to store uv's cache across workflow runs.
+The astral-sh/setup-uv has built-in support for
+persisting the cache:
Alternatively, you can manage the cache manually with the actions/cache action:
jobs:
+ install_job:
+ env:
+ # Configure a constant location for the uv cache
+ UV_CACHE_DIR: /tmp/.uv-cache
+
+ steps:
+ # ... setup up Python and uv ...
+
+ - name: Restore uv cache
+ uses: actions/cache@v4
+ with:
+ path: /tmp/.uv-cache
+ key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+ restore-keys: |
+ uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+ uv-${{ runner.os }}
+
+ # ... install packages, run tests, etc ...
+
+ - name: Minimize uv cache
+ run: uv cache prune --ci
+The uv cache prune --ci command is used to reduce the size of the cache and is optimized for CI.
+Its effect on performance is dependent on the packages being installed.
Tip
+If using uv pip, use requirements.txt instead of uv.lock in the cache key.
Note
+When using non-ephemeral, self-hosted runners the default cache directory can grow unbounded. +In this case, it may not be optimal to share the cache between jobs. Instead, move the cache +inside the GitHub Workspace and remove it once the job finishes using a +Post Job Hook.
+install_job:
+ env:
+ # Configure a relative location for the uv cache
+ UV_CACHE_DIR: ${{ github.workspace }}/.cache/uv
+Using a post job hook requires setting the ACTIONS_RUNNER_HOOK_JOB_STARTED environment
+variable on the self-hosted runner to the path of a cleanup script such as the one shown below.
uv pipIf using the uv pip interface instead of the uv project interface, uv requires a virtual
+environment by default. To allow installing packages into the system environment, use the --system
+flag on all uv invocations or set the UV_SYSTEM_PYTHON variable.
The UV_SYSTEM_PYTHON variable can be defined in at different scopes.
Opt-in for the entire workflow by defining it at the top level:
+ +Or, opt-in for a specific job in the workflow:
+ +Or, opt-in for a specific step in a job:
+steps:
+ - name: Install requirements
+ run: uv pip install -r requirements.txt
+ env:
+ UV_SYSTEM_PYTHON: 1
+To opt-out again, the --no-system flag can be used in any uv invocation.
If your project has dependencies on private GitHub +repositories, you will need to configure a personal access token (PAT) to allow uv to fetch +them.
+After creating a PAT that has read access to the private repositories, add it as a repository +secret.
+Then, you can use the gh CLI (which is installed in GitHub Actions
+runners by default) to configure a
+credential helper for Git to use the
+PAT for queries to repositories hosted on github.com.
For example, if you called your repository secret MY_PAT:
steps:
+ - name: Register the personal access token
+ run: echo "${{ secrets.MY_PAT }}" | gh auth login --with-token
+ - name: Configure the Git credential helper
+ run: gh auth setup-git
+uv can be used to build and publish your package to PyPI from GitHub Actions. We provide a +standalone example alongside this guide in +astral-sh/trusted-publishing-examples. +The workflow uses trusted publishing, so no credentials +need to be configured.
+In the example workflow, we use a script to test that the source distribution and the wheel are both +functional and we didn't miss any files. This step is recommended, but optional.
+First, add a release workflow to your project:
+name: "Publish"
+
+on:
+ push:
+ tags:
+ # Publish on any tag starting with a `v`, e.g., v0.1.0
+ - v*
+
+jobs:
+ run:
+ runs-on: ubuntu-latest
+ environment:
+ name: pypi
+ permissions:
+ id-token: write
+ contents: read
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v5
+ - name: Install uv
+ uses: astral-sh/setup-uv@v6
+ - name: Install Python 3.13
+ run: uv python install 3.13
+ - name: Build
+ run: uv build
+ # Check that basic features work and we didn't miss to include crucial files
+ - name: Smoke test (wheel)
+ run: uv run --isolated --no-project --with dist/*.whl tests/smoke_test.py
+ - name: Smoke test (source distribution)
+ run: uv run --isolated --no-project --with dist/*.tar.gz tests/smoke_test.py
+ - name: Publish
+ run: uv publish
+Then, create the environment defined in the workflow in the GitHub repository under "Settings" -> +"Environments".
+
Add a trusted publisher to your PyPI +project in the project settings under "Publishing". Ensure that all fields match with your GitHub +configuration.
+
After saving:
+
Finally, tag a release and push it. Make sure it starts with v to match the pattern in the
+workflow.
Astral provides Docker images with uv preinstalled. +Select a variant that is suitable for your workflow.
+variables:
+ UV_VERSION: "0.5"
+ PYTHON_VERSION: "3.12"
+ BASE_LAYER: bookworm-slim
+ # GitLab CI creates a separate mountpoint for the build directory,
+ # so we need to copy instead of using hard links.
+ UV_LINK_MODE: copy
+
+uv:
+ image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
+ script:
+ # your `uv` commands
+Note
+If you are using a distroless image, you have to specify the entrypoint: +
+Persisting the uv cache between workflow runs can improve performance.
+uv-install:
+ variables:
+ UV_CACHE_DIR: .uv-cache
+ cache:
+ - key:
+ files:
+ - uv.lock
+ paths:
+ - $UV_CACHE_DIR
+ script:
+ # Your `uv` commands
+ - uv cache prune --ci
+See the GitLab caching documentation for more details on +configuring caching.
+Using uv cache prune --ci at the end of the job is recommended to reduce cache size. See the uv
+cache documentation for more details.
uv pipIf using the uv pip interface instead of the uv project interface, uv requires a virtual
+environment by default. To allow installing packages into the system environment, use the --system
+flag on all uv invocations or set the UV_SYSTEM_PYTHON variable.
The UV_SYSTEM_PYTHON variable can be defined in at different scopes. You can read more about
+how variables and their precedence works in GitLab here
Opt-in for the entire workflow by defining it at the top level:
+ +To opt-out again, the --no-system flag can be used in any uv invocation.
When persisting the cache, you may want to use requirements.txt or pyproject.toml as
+your cache key files instead of uv.lock.
Learn how to integrate uv with other software:
+Or, explore the concept documentation for comprehensive breakdown of each +feature.
+ + + + + + + + + + + + + + + + + +The Jupyter notebook is a popular tool for interactive computing, data +analysis, and visualization. You can use Jupyter with uv in a few different ways, either to interact +with a project, or as a standalone tool.
+If you're working within a project, you can start a Jupyter +server with access to the project's virtual environment via the following:
+ +By default, jupyter lab will start the server at
+http://localhost:8888/lab.
Within a notebook, you can import your project's modules as you would in any other file in the
+project. For example, if your project depends on requests, import requests will import
+requests from the project's virtual environment.
If you're looking for read-only access to the project's virtual environment, then there's nothing +more to it. However, if you need to install additional packages from within the notebook, there are +a few extra details to consider.
+If you need to install packages from within the notebook, we recommend creating a dedicated kernel +for your project. Kernels enable the Jupyter server to run in one environment, with individual +notebooks running in their own, separate environments.
+In the context of uv, we can create a kernel for a project while installing Jupyter itself in an
+isolated environment, as in uv run --with jupyter jupyter lab. Creating a kernel for the project
+ensures that the notebook is hooked up to the correct environment, and that any packages installed
+from within the notebook are installed into the project's virtual environment.
To create a kernel, you'll need to install ipykernel as a development dependency:
Then, you can create the kernel for project with:
From there, start the server with:
+ +When creating a notebook, select the project kernel from the dropdown. Then use !uv add pydantic
+to add pydantic to the project's dependencies, or !uv pip install pydantic to install pydantic
+into the project's virtual environment without persisting the change to the project pyproject.toml
+or uv.lock files. Either command will make import pydantic work within the notebook.
If you don't want to create a kernel, you can still install packages from within the notebook. +However, there are a few caveats to consider.
+Though uv run --with jupyter runs in an isolated environment, within the notebook itself,
+!uv add and related commands will modify the project's environment, even without a kernel.
For example, running !uv add pydantic from within a notebook will add pydantic to the project's
+dependencies and virtual environment, such that import pydantic will work immediately, without
+further configuration or a server restart.
However, since the Jupyter server is the "active" environment, !uv pip install will install
+package's into Jupyter's environment, not the project environment. Such dependencies will persist
+for the lifetime of the Jupyter server, but may disappear on subsequent jupyter invocations.
If you're working with a notebook that relies on pip (e.g., via the %pip magic), you can include
+pip in your project's virtual environment by running uv venv --seed prior to starting the Jupyter
+server. For example, given:
Subsequent %pip install invocations within the notebook will install packages into the project's
+virtual environment. However, such modifications will not be reflected in the project's
+pyproject.toml or uv.lock files.
If you ever need ad hoc access to a notebook (i.e., to run a Python snippet interactively), you can
+start a Jupyter server at any time with uv tool run jupyter lab. This will run a Jupyter server in
+an isolated environment.
If you need to run Jupyter in a virtual environment that isn't associated with a
+project (e.g., has no pyproject.toml or uv.lock), you can do
+so by adding Jupyter to the environment directly. For example:
From here, import pydantic will work within the notebook, and you can install additional packages
+via !uv pip install, or even !pip install.
You can also engage with Jupyter notebooks from within an editor like VS Code. To connect a +uv-managed project to a Jupyter notebook within VS Code, we recommend creating a kernel for the +project, as in the following:
+# Create a project.
+$ uv init project
+
+# Move into the project directory.
+$ cd project
+
+# Add ipykernel as a dev dependency.
+$ uv add --dev ipykernel
+
+# Open the project in VS Code.
+$ code .
+Once the project directory is open in VS Code, you can create a new Jupyter notebook by selecting
+"Create: New Jupyter Notebook" from the command palette. When prompted to select a kernel, choose
+"Python Environments" and select the virtual environment you created earlier (e.g.,
+.venv/bin/python on macOS and Linux, or .venv\Scripts\python on Windows).
Note
+VS Code requires ipykernel to be present in the project environment. If you'd prefer to avoid
+adding ipykernel as a dev dependency, you can install it directly into the project environment
+with uv pip install ipykernel.
If you need to manipulate the project's environment from within the notebook, you may need to add
+uv as an explicit development dependency:
From there, you can use !uv add pydantic to add pydantic to the project's dependencies, or
+!uv pip install pydantic to install pydantic into the project's virtual environment without
+updating the project's pyproject.toml or uv.lock files.
marimo is an open-source Python notebook that blends +interactive computing with the reproducibility and reusability of traditional software, letting you +version with Git, run as scripts, and share as apps. Because marimo notebooks are stored as pure +Python scripts, they are able to integrate tightly with uv.
+You can readily use marimo as a standalone tool, as self-contained scripts, in projects, and in +non-project environments.
+For ad-hoc access to marimo notebooks, start a marimo server at any time in an isolated environment +with:
+ +Start a specific notebook with:
+ +Because marimo notebooks are stored as Python scripts, they can encapsulate their own dependencies
+using inline script metadata, via uv's support for scripts. For example,
+to add numpy as a dependency to your notebook, use this command:
To interactively edit a notebook containing inline script metadata, use:
+ +marimo will automatically use uv to start your notebook in an isolated virtual environment with your +script's dependencies. Packages installed from the marimo UI will automatically be added to the +notebook's script metadata.
+You can optionally run these notebooks as Python scripts, without opening an interactive session:
+ +If you're working within a project, you can start a marimo +notebook with access to the project's virtual environment via the following command (assuming marimo +is a project dependency):
+ +To make additional packages available to your notebook, either add them to your project with
+uv add, or use marimo's built-in package installation UI, which will invoke uv add on your
+behalf.
If marimo is not a project dependency, you can still run a notebook with the following command:
+ +This will let you import your project's modules while editing your notebook. However, packages +installed via marimo's UI when running in this way will not be added to your project, and may +disappear on subsequent marimo invocations.
+To run marimo in a virtual environment that isn't associated with a +project, add marimo to the environment directly:
+ +From here, import numpy will work within the notebook, and marimo's UI installer will add packages
+to the environment with uv pip install on your behalf.
Regardless of how your dependencies are managed (with inline script metadata, within a project, or +with a non-project environment), you can run marimo notebooks as scripts with:
+ +This executes your notebook as a Python script, without opening an interactive session in your +browser.
+ + + + + + + + + + + + + + + + + + + + +An official pre-commit hook is provided at
+astral-sh/uv-pre-commit.
To use uv with pre-commit, add one of the following examples to the repos list in the
+.pre-commit-config.yaml.
To make sure your uv.lock file is up to date even if your pyproject.toml file was changed:
repos:
+ - repo: https://github.com/astral-sh/uv-pre-commit
+ # uv version.
+ rev: 0.9.8
+ hooks:
+ - id: uv-lock
+To keep a requirements.txt file in sync with your uv.lock file:
repos:
+ - repo: https://github.com/astral-sh/uv-pre-commit
+ # uv version.
+ rev: 0.9.8
+ hooks:
+ - id: uv-export
+To compile requirements files:
+repos:
+ - repo: https://github.com/astral-sh/uv-pre-commit
+ # uv version.
+ rev: 0.9.8
+ hooks:
+ # Compile requirements
+ - id: pip-compile
+ args: [requirements.in, -o, requirements.txt]
+To compile alternative requirements files, modify args and files:
repos:
+ - repo: https://github.com/astral-sh/uv-pre-commit
+ # uv version.
+ rev: 0.9.8
+ hooks:
+ # Compile requirements
+ - id: pip-compile
+ args: [requirements-dev.in, -o, requirements-dev.txt]
+ files: ^requirements-dev\.(in|txt)$
+To run the hook over multiple files at the same time, add additional entries:
+repos:
+ - repo: https://github.com/astral-sh/uv-pre-commit
+ # uv version.
+ rev: 0.9.8
+ hooks:
+ # Compile requirements
+ - id: pip-compile
+ name: pip-compile requirements.in
+ args: [requirements.in, -o, requirements.txt]
+ - id: pip-compile
+ name: pip-compile requirements-dev.in
+ args: [requirements-dev.in, -o, requirements-dev.txt]
+ files: ^requirements-dev\.(in|txt)$
+The PyTorch ecosystem is a popular choice for deep learning research and +development. You can use uv to manage PyTorch projects and PyTorch dependencies across different +Python versions and environments, even controlling for the choice of accelerator (e.g., CPU-only vs. +CUDA).
+Note
+Some of the features outlined in this guide require uv version 0.5.3 or later. We recommend upgrading prior to configuring PyTorch.
+From a packaging perspective, PyTorch has a few uncommon characteristics:
+2.5.1+cpu, 2.5.1+cu121, etc.+cpu
+ builds are published on https://download.pytorch.org/whl/cpu, while the +cu121 builds are
+ published on https://download.pytorch.org/whl/cu121.As such, the necessary packaging configuration will vary depending on both the platforms you need to +support and the accelerators you want to enable.
+To start, consider the following (default) configuration, which would be generated by running
+uv init --python 3.12 followed by uv add torch torchvision.
In this case, PyTorch would be installed from PyPI, which hosts CPU-only wheels for Windows and +macOS, and GPU-accelerated wheels on Linux (targeting CUDA 12.6):
+[project]
+name = "project"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+ "torch>=2.7.0",
+ "torchvision>=0.22.0",
+]
+Supported Python versions
+At time of writing, PyTorch does not yet publish wheels for Python 3.14; as such projects with
+requires-python = ">=3.14" may fail to resolve. See the
+compatibility matrix.
This is a valid configuration for projects that want to use CPU builds on Windows and macOS, and +CUDA-enabled builds on Linux. However, if you need to support different platforms or accelerators, +you'll need to configure the project accordingly.
+In some cases, you may want to use a specific PyTorch variant across all platforms. For example, you +may want to use the CPU-only builds on Linux too.
+In such cases, the first step is to add the relevant PyTorch index to your pyproject.toml:
We recommend the use of explicit = true to ensure that the index is only used for torch,
+torchvision, and other PyTorch-related packages, as opposed to generic dependencies like jinja2,
+which should continue to be sourced from the default index (PyPI).
Next, update the pyproject.toml to point torch and torchvision to the desired index:
PyTorch doesn't publish CUDA builds for macOS. As such, we gate on sys_platform to instruct uv to use
+the PyTorch index on Linux and Windows, but fall back to PyPI on macOS:
PyTorch doesn't publish CUDA builds for macOS. As such, we gate on sys_platform to instruct uv to limit
+the PyTorch index to Linux and Windows, falling back to PyPI on macOS:
PyTorch doesn't publish CUDA builds for macOS. As such, we gate on sys_platform to instruct uv to limit
+the PyTorch index to Linux and Windows, falling back to PyPI on macOS:
PyTorch doesn't publish ROCm6 builds for macOS or Windows. As such, we gate on sys_platform to instruct uv
+to limit the PyTorch index to Linux, falling back to PyPI on macOS and Windows:
[tool.uv.sources]
+torch = [
+ { index = "pytorch-rocm", marker = "sys_platform == 'linux'" },
+]
+torchvision = [
+ { index = "pytorch-rocm", marker = "sys_platform == 'linux'" },
+]
+# ROCm6 support relies on `pytorch-triton-rocm`, which should also be installed from the PyTorch index
+# (and included in `project.dependencies`).
+pytorch-triton-rocm = [
+ { index = "pytorch-rocm", marker = "sys_platform == 'linux'" },
+]
+PyTorch doesn't publish Intel GPU builds for macOS. As such, we gate on sys_platform to instruct uv to limit
+the PyTorch index to Linux and Windows, falling back to PyPI on macOS:
[tool.uv.sources]
+torch = [
+ { index = "pytorch-xpu", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+]
+torchvision = [
+ { index = "pytorch-xpu", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+]
+# Intel GPU support relies on `pytorch-triton-xpu`, which should also be installed from the PyTorch index
+# (and included in `project.dependencies`).
+pytorch-triton-xpu = [
+ { index = "pytorch-xpu", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+]
+As a complete example, the following project would use PyTorch's CPU-only builds on all platforms:
+[project]
+name = "project"
+version = "0.1.0"
+requires-python = ">=3.12.0"
+dependencies = [
+ "torch>=2.7.0",
+ "torchvision>=0.22.0",
+]
+
+[tool.uv.sources]
+torch = [
+ { index = "pytorch-cpu" },
+]
+torchvision = [
+ { index = "pytorch-cpu" },
+]
+
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+In some cases, you may want to use CPU-only builds in one environment (e.g., macOS and Windows), and +CUDA-enabled builds in another (e.g., Linux).
+With tool.uv.sources, you can use environment markers to specify the desired index for each
+platform. For example, the following configuration would use PyTorch's CUDA-enabled builds on Linux,
+and CPU-only builds on all other platforms (e.g., macOS and Windows):
[project]
+name = "project"
+version = "0.1.0"
+requires-python = ">=3.12.0"
+dependencies = [
+ "torch>=2.7.0",
+ "torchvision>=0.22.0",
+]
+
+[tool.uv.sources]
+torch = [
+ { index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
+ { index = "pytorch-cu128", marker = "sys_platform == 'linux'" },
+]
+torchvision = [
+ { index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
+ { index = "pytorch-cu128", marker = "sys_platform == 'linux'" },
+]
+
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[[tool.uv.index]]
+name = "pytorch-cu128"
+url = "https://download.pytorch.org/whl/cu128"
+explicit = true
+Similarly, the following configuration would use PyTorch's AMD GPU builds on Linux, and CPU-only +builds on Windows and macOS (by way of falling back to PyPI):
+[project]
+name = "project"
+version = "0.1.0"
+requires-python = ">=3.12.0"
+dependencies = [
+ "torch>=2.7.0",
+ "torchvision>=0.22.0",
+ "pytorch-triton-rocm>=3.3.0 ; sys_platform == 'linux'",
+]
+
+[tool.uv.sources]
+torch = [
+ { index = "pytorch-rocm", marker = "sys_platform == 'linux'" },
+]
+torchvision = [
+ { index = "pytorch-rocm", marker = "sys_platform == 'linux'" },
+]
+pytorch-triton-rocm = [
+ { index = "pytorch-rocm", marker = "sys_platform == 'linux'" },
+]
+
+[[tool.uv.index]]
+name = "pytorch-rocm"
+url = "https://download.pytorch.org/whl/rocm6.3"
+explicit = true
+Or, for Intel GPU builds:
+[project]
+name = "project"
+version = "0.1.0"
+requires-python = ">=3.12.0"
+dependencies = [
+ "torch>=2.7.0",
+ "torchvision>=0.22.0",
+ "pytorch-triton-xpu>=3.3.0 ; sys_platform == 'win32' or sys_platform == 'linux'",
+]
+
+[tool.uv.sources]
+torch = [
+ { index = "pytorch-xpu", marker = "sys_platform == 'win32' or sys_platform == 'linux'" },
+]
+torchvision = [
+ { index = "pytorch-xpu", marker = "sys_platform == 'win32' or sys_platform == 'linux'" },
+]
+pytorch-triton-xpu = [
+ { index = "pytorch-xpu", marker = "sys_platform == 'win32' or sys_platform == 'linux'" },
+]
+
+[[tool.uv.index]]
+name = "pytorch-xpu"
+url = "https://download.pytorch.org/whl/xpu"
+explicit = true
+In some cases, you may want to use CPU-only builds in some cases, but CUDA-enabled builds in others,
+with the choice toggled by a user-provided extra (e.g., uv sync --extra cpu vs.
+uv sync --extra cu128).
With tool.uv.sources, you can use extra markers to specify the desired index for each enabled
+extra. For example, the following configuration would use PyTorch's CPU-only for
+uv sync --extra cpu and CUDA-enabled builds for uv sync --extra cu128:
[project]
+name = "project"
+version = "0.1.0"
+requires-python = ">=3.12.0"
+dependencies = []
+
+[project.optional-dependencies]
+cpu = [
+ "torch>=2.7.0",
+ "torchvision>=0.22.0",
+]
+cu128 = [
+ "torch>=2.7.0",
+ "torchvision>=0.22.0",
+]
+
+[tool.uv]
+conflicts = [
+ [
+ { extra = "cpu" },
+ { extra = "cu128" },
+ ],
+]
+
+[tool.uv.sources]
+torch = [
+ { index = "pytorch-cpu", extra = "cpu" },
+ { index = "pytorch-cu128", extra = "cu128" },
+]
+torchvision = [
+ { index = "pytorch-cpu", extra = "cpu" },
+ { index = "pytorch-cu128", extra = "cu128" },
+]
+
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[[tool.uv.index]]
+name = "pytorch-cu128"
+url = "https://download.pytorch.org/whl/cu128"
+explicit = true
+Note
+Since GPU-accelerated builds aren't available on macOS, the above configuration will fail to install
+on macOS when the cu128 extra is enabled.
uv pip interfaceWhile the above examples are focused on uv's project interface (uv lock, uv sync, uv run,
+etc.), PyTorch can also be installed via the uv pip interface.
PyTorch itself offers a dedicated interface to determine +the appropriate pip command to run for a given target configuration. For example, you can install +stable, CPU-only PyTorch on Linux with:
+ +To use the same workflow with uv, replace pip3 with uv pip:
uv supports automatic selection of the appropriate PyTorch index via the --torch-backend=auto
+command-line argument (or the UV_TORCH_BACKEND=auto environment variable), as in:
$ # With a command-line argument.
+$ uv pip install torch --torch-backend=auto
+
+$ # With an environment variable.
+$ UV_TORCH_BACKEND=auto uv pip install torch
+When enabled, uv will query for the installed CUDA driver, AMD GPU versions, and Intel GPU presence,
+then use the most-compatible PyTorch index for all relevant packages (e.g., torch, torchvision,
+etc.). If no such GPU is found, uv will fall back to the CPU-only index. uv will continue to respect
+existing index configuration for any packages outside the PyTorch ecosystem.
You can also select a specific backend (e.g., CUDA 12.6) with --torch-backend=cu126 (or
+UV_TORCH_BACKEND=cu126):
$ # With a command-line argument.
+$ uv pip install torch torchvision --torch-backend=cu126
+
+$ # With an environment variable.
+$ UV_TORCH_BACKEND=cu126 uv pip install torch torchvision
+At present, --torch-backend is only available in the uv pip interface.
Learn how to migrate from other tools to uv:
+ +Note
+Other guides, such as migrating from another project management tool, or from pip to uv pip
+are not yet available. See #5200 to track
+progress.
Or, explore the integration guides to learn how to use uv with other +software.
+ + + + + + + + + + + + + + + + + +This guide will discuss converting from a pip and pip-tools workflow centered on requirements
+files to uv's project workflow using a pyproject.toml and uv.lock file.
Note
+If you're looking to migrate from pip and pip-tools to uv's drop-in interface or from an
+existing workflow where you're already using a pyproject.toml, those guides are not yet
+written. See #5200 to track progress.
We'll start with an overview of developing with pip, then discuss migrating to uv.
Tip
+If you're familiar with the ecosystem, you can jump ahead to the +requirements file import instructions.
+When you want to use a package in your project, you need to install it first. pip supports
+imperative installation of packages, e.g.:
This installs the package into the environment that pip is installed in. This may be a virtual
+environment, or, the global environment of your system's Python installation.
Then, you can run a Python script that requires the package:
+ +It's best practice to create a virtual environment for each project, to avoid mixing packages +between them. For example:
+ +We will revisit this topic in the project environments section below.
+When sharing projects with others, it's useful to declare all the packages you require upfront.
+pip supports installing requirements from a file, e.g.:
Notice above that fastapi is not "locked" to a specific version — each person working on the
+project may have a different version of fastapi installed. pip-tools was created to improve this
+experience.
When using pip-tools, requirements files specify both the dependencies for your project and lock
+dependencies to a specific version — the file extension is used to differentiate between the two.
+For example, if you require fastapi and pydantic, you'd specify these in a requirements.in
+file:
Notice there's a version constraint on pydantic — this means only pydantic versions later than
+2.0.0 can be used. In contrast, fastapi does not have a version constraint — any version can be
+used.
These dependencies can be compiled into a requirements.txt file:
annotated-types==0.7.0
+ # via pydantic
+anyio==4.8.0
+ # via starlette
+fastapi==0.115.11
+ # via -r requirements.in
+idna==3.10
+ # via anyio
+pydantic==2.10.6
+ # via
+ # -r requirements.in
+ # fastapi
+pydantic-core==2.27.2
+ # via pydantic
+sniffio==1.3.1
+ # via anyio
+starlette==0.46.1
+ # via fastapi
+typing-extensions==4.12.2
+ # via
+ # fastapi
+ # pydantic
+ # pydantic-core
+Here, all the versions constraints are exact. Only a single version of each package can be used.
+The above example was generated with uv pip compile, but could also be generated with
+pip-compile from pip-tools.
Though less common, the requirements.txt can also be generated using pip freeze, by first
+installing the input dependencies into the environment then exporting the installed versions:
annotated-types==0.7.0
+anyio==4.8.0
+fastapi==0.115.11
+idna==3.10
+pydantic==2.10.6
+pydantic-core==2.27.2
+sniffio==1.3.1
+starlette==0.46.1
+typing-extensions==4.12.2
+After compiling dependencies into a locked set of versions, these files are committed to version +control and distributed with the project.
+Then, when someone wants to use the project, they install from the requirements file:
+ + + +The requirements file format can only describe a single set of dependencies at once. This means if
+you have additional groups of dependencies, such as development dependencies, they need separate
+files. For example, we'll create a -dev dependency file:
Notice the base requirements are included with -r requirements.in. This ensures your development
+environment considers all of the dependencies together. The -c requirements.txt constrains the
+package version to ensure that the requirements-dev.txt uses the same versions as
+requirements.txt.
Note
+It's common to use -r requirements.txt directly instead of using both
+-r requirements.in, and -c requirements.txt. There's no difference in the resulting package
+versions, but using both files produces annotations which allow you to determine which
+dependencies are direct (annotated with -r requirements.in) and which are indirect (only
+annotated with -c requirements.txt).
The compiled development dependencies look like:
+annotated-types==0.7.0
+ # via
+ # -c requirements.txt
+ # pydantic
+anyio==4.8.0
+ # via
+ # -c requirements.txt
+ # starlette
+fastapi==0.115.11
+ # via
+ # -c requirements.txt
+ # -r requirements.in
+idna==3.10
+ # via
+ # -c requirements.txt
+ # anyio
+iniconfig==2.0.0
+ # via pytest
+packaging==24.2
+ # via pytest
+pluggy==1.5.0
+ # via pytest
+pydantic==2.10.6
+ # via
+ # -c requirements.txt
+ # -r requirements.in
+ # fastapi
+pydantic-core==2.27.2
+ # via
+ # -c requirements.txt
+ # pydantic
+pytest==8.3.5
+ # via -r requirements-dev.in
+sniffio==1.3.1
+ # via
+ # -c requirements.txt
+ # anyio
+starlette==0.46.1
+ # via
+ # -c requirements.txt
+ # fastapi
+typing-extensions==4.12.2
+ # via
+ # -c requirements.txt
+ # fastapi
+ # pydantic
+ # pydantic-core
+As with the base dependency files, these are committed to version control and distributed with the +project. When someone wants to work on the project, they'll install from the requirements file:
+ +When compiling dependencies with pip or pip-tools, the result is only usable on the same
+platform as it is generated on. This poses a problem for projects which need to be usable on
+multiple platforms, such as Windows and macOS.
For example, take a simple dependency:
+ +On Linux, this compiles to:
+ +While on Windows, this compiles to:
+ +colorama is a Windows-only dependency of tqdm.
When using pip and pip-tools, a project needs to declare a requirements lock file for each
+supported platform.
Note
+uv's resolver can compile dependencies for multiple platforms at once (see "universal resolution"),
+allowing you to use a single requirements.txt for all platforms:
colorama==0.4.6 ; sys_platform == 'win32'
+ # via tqdm
+tqdm==4.67.1
+ # via -r requirements.in
+This resolution mode is also used when using a pyproject.toml and uv.lock.
pyproject.tomlThe pyproject.toml is a standardized file for Python project metadata. It replaces
+requirements.in files, allowing you to represent arbitrary groups of project dependencies. It also
+provides a centralized location for metadata about your project, such as the build system or tool
+settings.
For example, the requirements.in and requirements-dev.in files above can be translated to a
+pyproject.toml as follows:
[project]
+name = "example"
+version = "0.0.1"
+dependencies = [
+ "fastapi",
+ "pydantic>2"
+]
+
+[dependency-groups]
+dev = ["pytest"]
+We'll discuss the commands necessary to automate these imports below.
+uv uses a lockfile (uv.lock) file to lock package versions. The format of this file is specific to
+uv, allowing uv to support advanced features. It replaces requirements.txt files.
The lockfile will be automatically created and populated when adding dependencies, but you can
+explicitly create it with uv lock.
Unlike requirements.txt files, the uv.lock file can represent arbitrary groups of dependencies,
+so multiple files are not needed to lock development dependencies.
The uv lockfile is always universal, so +multiple files are not needed to +lock dependencies for each platform. This ensures that all +developers are using consistent, locked versions of dependencies regardless of their machine.
+The uv lockfile also supports concepts like
+pinning packages to specific indexes,
+which is not representable in requirements.txt files.
Tip
+If you only need to lock for a subset of platforms, use the
+tool.uv.environments setting
+to limit the resolution and lockfile.
To learn more, see the lockfile documentation.
+First, create a pyproject.toml if you have not already:
Then, the easiest way to import requirements is with uv add:
However, there is some nuance to this transition. Notice we used the requirements.in file, which
+does not pin to exact versions of packages so uv will solve for new versions of these packages. You
+may want to continue using your previously locked versions from your requirements.txt so, when
+switching over to uv, none of your dependency versions change.
The solution is to add your locked versions as constraints. uv supports using these on add to
+preserve locked versions:
Your existing versions will be retained when producing a uv.lock file.
If your platform-specific dependencies have been compiled into separate files, you can still
+transition to a universal lockfile. However, you cannot just use -c to specify constraints from
+your existing platform-specific requirements.txt files because they do not include markers
+describing the environment and will consequently conflict.
To add the necessary markers, use uv pip compile to convert your existing files. For example,
+given the following:
The markers can be added with:
+$ uv pip compile requirements.in -o requirements-win.txt --python-platform windows --no-strip-markers
+Notice the resulting output includes a Windows marker on colorama:
colorama==0.4.6 ; sys_platform == 'win32'
+ # via tqdm
+tqdm==4.67.1
+ # via -r requirements.in
+When using -o, uv will constrain the versions to match the existing output file, if it can.
Markers can be added for other platforms by changing the --python-platform and -o values for
+each requirements file you need to import, e.g., to linux and macos.
Once each requirements.txt file has been transformed, the dependencies can be imported to the
+pyproject.toml and uv.lock with uv add:
As discussed in the development dependencies section, it's common to +have groups of dependencies for development purposes.
+To import development dependencies, use the --dev flag during uv add:
If the requirements-dev.in includes the parent requirements.in via -r, it will need to be
+stripped to avoid adding the base requirements to the dev dependency group. The following example
+uses sed to strip lines that start with -r, then pipes the result to uv add:
In addition to the dev dependency group, uv supports arbitrary group names. For example, if you
+also have a dedicated set of dependencies for building your documentation, those can be imported to
+a docs group:
Unlike pip, uv is not centered around the concept of an "active" virtual environment. Instead, uv
+uses a dedicated virtual environment for each project in a .venv directory. This environment is
+automatically managed, so when you run a command, like uv add, the environment is synced with the
+project dependencies.
The preferred way to execute commands in the environment is with uv run, e.g.:
Prior to every uv run invocation, uv will verify that the lockfile is up-to-date with the
+pyproject.toml, and that the environment is up-to-date with the lockfile, keeping your project
+in-sync without the need for manual intervention. uv run guarantees that your command is run in a
+consistent, locked environment.
The project environment can also be explicitly created with uv sync, e.g., for use with editors.
Note
+When in projects, uv will prefer a .venv in the project directory and ignore the active
+environment as declared by the VIRTUAL_ENV variable by default. You can opt-in to using the
+active environment with the --active flag.
To learn more, see the +project environment documentation.
+Now that you've migrated to uv, take a look at the +project concept page for more details about uv projects.
+ + + + + + + + + + + + + + + + + +uv supports building Python packages into source and binary distributions via uv build and
+uploading them to a registry with uv publish.
Before attempting to publish your project, you'll want to make sure it's ready to be packaged for +distribution.
+If your project does not include a [build-system] definition in the pyproject.toml, uv will not
+build it by default. This means that your project may not be ready for distribution. Read more about
+the effect of declaring a build system in the
+project concept documentation.
Note
+If you have internal packages that you do not want to be published, you can mark them as +private:
+ +This setting makes PyPI reject your uploaded package from publishing. It does not affect +security or privacy settings on alternative registries.
+We also recommend only generating per-project PyPI API tokens: +Without a PyPI token matching the project, it can't be accidentally published.
+Build your package with uv build:
By default, uv build will build the project in the current directory, and place the built
+artifacts in a dist/ subdirectory.
Alternatively, uv build <SRC> will build the package in the specified directory, while
+uv build --package <PACKAGE> will build the specified package within the current workspace.
Info
+By default, uv build respects tool.uv.sources when resolving build dependencies from the
+build-system.requires section of the pyproject.toml. When publishing a package, we recommend
+running uv build --no-sources to ensure that the package builds correctly when tool.uv.sources
+is disabled, as is the case when using other build tools, like pypa/build.
The uv version command provides conveniences for updating the version of your package before you
+publish it.
+See the project docs for reading your package's version.
To update to an exact version, provide it as a positional argument:
+ +To preview the change without updating the pyproject.toml, use the --dry-run flag:
To increase the version of your package semantics, use the --bump option:
The --bump option supports the following common version components: major, minor, patch,
+stable, alpha, beta, rc, post, and dev. When provided more than once, the components
+will be applied in order, from largest (major) to smallest (dev).
To move from a stable to pre-release version, bump one of the major, minor, or patch components in +addition to the pre-release component:
+$ uv version --bump patch --bump beta
+hello-world 1.3.0 => 1.3.1b1
+$ uv version --bump major --bump alpha
+hello-world 1.3.0 => 2.0.0a1
+When moving from a pre-release to a new pre-release version, just bump the relevant pre-release +component:
+ +When moving from a pre-release to a stable version, the stable option can be used to clear the
+pre-release component:
Info
+By default, when uv version modifies the project it will perform a lock and sync. To
+prevent locking and syncing, use --frozen, or, to just prevent syncing, use --no-sync.
Note
+A complete guide to publishing from GitHub Actions to PyPI can be found in the +GitHub Guide
+Publish your package with uv publish:
Set a PyPI token with --token or UV_PUBLISH_TOKEN, or set a username with --username or
+UV_PUBLISH_USERNAME and password with --password or UV_PUBLISH_PASSWORD. For publishing to
+PyPI from GitHub Actions or another Trusted Publisher, you don't need to set any credentials.
+Instead,
+add a trusted publisher to the PyPI project.
Note
+PyPI does not support publishing with username and password anymore, instead you need to
+generate a token. Using a token is equivalent to setting --username __token__ and using the
+token as password.
If you're using a custom index through [[tool.uv.index]], add publish-url and use
+uv publish --index <name>. For example:
[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+Note
+When using uv publish --index <name>, the pyproject.toml must be present, i.e., you need to
+have a checkout step in a publish CI job.
Even though uv publish retries failed uploads, it can happen that publishing fails in the middle,
+with some files uploaded and some files still missing. With PyPI, you can retry the exact same
+command, existing identical files will be ignored. With other registries, use
+--check-url <index url> with the index URL (not the publishing URL) the packages belong to. When
+using --index, the index URL is used as check URL. uv will skip uploading files that are identical
+to files in the registry, and it will also handle raced parallel uploads. Note that existing files
+need to match exactly with those previously uploaded to the registry, this avoids accidentally
+publishing source distribution and wheels with different contents for the same version.
Test that the package can be installed and imported with uv run:
The --no-project flag is used to avoid installing the package from your local project directory.
Tip
+If you have recently installed the package, you may need to include the
+--refresh-package <PACKAGE> option to avoid using a cached version of the package.
To learn more about publishing packages, check out the +PyPA guides on building +and publishing.
+Or, read on for guides on integrating uv with other software.
+ + + + + + + + + + + + + + + + + + + + +uv supports managing Python projects, which define their dependencies in a pyproject.toml file.
You can create a new Python project using the uv init command:
Alternatively, you can initialize a project in the working directory:
+ +uv will create the following files:
+ +The main.py file contains a simple "Hello world" program. Try it out with uv run:
A project consists of a few important parts that work together and allow uv to manage your project.
+In addition to the files created by uv init, uv will create a virtual environment and uv.lock
+file in the root of your project the first time you run a project command, i.e., uv run,
+uv sync, or uv lock.
A complete listing would look like:
+.
+├── .venv
+│ ├── bin
+│ ├── lib
+│ └── pyvenv.cfg
+├── .python-version
+├── README.md
+├── main.py
+├── pyproject.toml
+└── uv.lock
+pyproject.tomlThe pyproject.toml contains metadata about your project:
[project]
+name = "hello-world"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+dependencies = []
+You'll use this file to specify dependencies, as well as details about the project such as its
+description or license. You can edit this file manually, or use commands like uv add and
+uv remove to manage your project from the terminal.
Tip
+See the official pyproject.toml guide
+for more details on getting started with the pyproject.toml format.
You'll also use this file to specify uv configuration options
+in a [tool.uv] section.
.python-versionThe .python-version file contains the project's default Python version. This file tells uv which
+Python version to use when creating the project's virtual environment.
.venvThe .venv folder contains your project's virtual environment, a Python environment that is
+isolated from the rest of your system. This is where uv will install your project's dependencies.
See the project environment documentation +for more details.
+uv.lockuv.lock is a cross-platform lockfile that contains exact information about your project's
+dependencies. Unlike the pyproject.toml which is used to specify the broad requirements of your
+project, the lockfile contains the exact resolved versions that are installed in the project
+environment. This file should be checked into version control, allowing for consistent and
+reproducible installations across machines.
uv.lock is a human-readable TOML file but is managed by uv and should not be edited manually.
See the lockfile documentation for more details.
+You can add dependencies to your pyproject.toml with the uv add command. This will also update
+the lockfile and project environment:
You can also specify version constraints or alternative sources:
+$ # Specify a version constraint
+$ uv add 'requests==2.31.0'
+
+$ # Add a git dependency
+$ uv add git+https://github.com/psf/requests
+If you're migrating from a requirements.txt file, you can use uv add with the -r flag to add
+all dependencies from the file:
$ # Add all dependencies from `requirements.txt`.
+$ uv add -r requirements.txt -c constraints.txt
+To remove a package, you can use uv remove:
To upgrade a package, run uv lock with the --upgrade-package flag:
The --upgrade-package flag will attempt to update the specified package to the latest compatible
+version, while keeping the rest of the lockfile intact.
See the documentation on managing dependencies for more +details.
+The uv version command can be used to read your package's version.
To get the version of your package, run uv version:
To get the version without the package name, use the --short option:
To get version information in a JSON format, use the --output-format json option:
$ uv version --output-format json
+{
+ "package_name": "hello-world",
+ "version": "0.7.0",
+ "commit_info": null
+}
+See the publishing guide for details on updating your package +version.
+uv run can be used to run arbitrary scripts or commands in your project environment.
Prior to every uv run invocation, uv will verify that the lockfile is up-to-date with the
+pyproject.toml, and that the environment is up-to-date with the lockfile, keeping your project
+in-sync without the need for manual intervention. uv run guarantees that your command is run in a
+consistent, locked environment.
For example, to use flask:
Or, to run a script:
+ + +Alternatively, you can use uv sync to manually update the environment then activate it before
+executing a command:
Note
+The virtual environment must be active to run scripts and commands in the project without uv run. Virtual environment activation differs per shell and platform.
See the documentation on running commands and scripts in projects for +more details.
+uv build can be used to build source distributions and binary distributions (wheel) for your
+project.
By default, uv build will build the project in the current directory, and place the built
+artifacts in a dist/ subdirectory:
See the documentation on building projects for more details.
+To learn more about working on projects with uv, see the +projects concept page and the +command reference.
+Or, read on to learn how to build and publish your project to a package index.
+ + + + + + + + + + + + + + + + + + + + +A Python script is a file intended for standalone execution, e.g., with python <script>.py. Using
+uv to execute scripts ensures that script dependencies are managed without manually managing
+environments.
Note
+If you are not familiar with Python environments: every Python installation has an environment +that packages can be installed in. Typically, creating virtual environments is recommended to +isolate packages required by each script. uv automatically manages virtual environments for you +and prefers a declarative approach to dependencies.
+If your script has no dependencies, you can execute it with uv run:
Similarly, if your script depends on a module in the standard library, there's nothing more to do:
+ + +Arguments may be provided to the script:
+ + +Additionally, your script can be read directly from stdin:
+ +Or, if your shell supports here-documents:
+ +Note that if you use uv run in a project, i.e., a directory with a pyproject.toml, it will
+install the current project before running the script. If your script does not depend on the
+project, use the --no-project flag to skip this:
$ # Note: the `--no-project` flag must be provided _before_ the script name.
+$ uv run --no-project example.py
+See the projects guide for more details on working in projects.
+When your script requires other packages, they must be installed into the environment that the +script runs in. uv prefers to create these environments on-demand instead of using a long-lived +virtual environment with manually managed dependencies. This requires explicit declaration of +dependencies that are required for the script. Generally, it's recommended to use a +project or inline metadata to declare +dependencies, but uv supports requesting dependencies per invocation as well.
+For example, the following script requires rich.
import time
+from rich.progress import track
+
+for i in track(range(20), description="For example:"):
+ time.sleep(0.05)
+If executed without specifying a dependency, this script will fail:
+$ uv run --no-project example.py
+Traceback (most recent call last):
+ File "/Users/astral/example.py", line 2, in <module>
+ from rich.progress import track
+ModuleNotFoundError: No module named 'rich'
+Request the dependency using the --with option:
$ uv run --with rich example.py
+For example: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:01
+Constraints can be added to the requested dependency if specific versions are needed:
+ +Multiple dependencies can be requested by repeating with --with option.
Note that if uv run is used in a project, these dependencies will be included in addition to
+the project's dependencies. To opt-out of this behavior, use the --no-project flag.
Python recently added a standard format for
+inline script metadata.
+It allows for selecting Python versions and defining dependencies. Use uv init --script to
+initialize scripts with the inline metadata:
The inline metadata format allows the dependencies for a script to be declared in the script itself.
+uv supports adding and updating inline script metadata for you. Use uv add --script to declare the
+dependencies for the script:
This will add a script section at the top of the script declaring the dependencies using TOML:
# /// script
+# dependencies = [
+# "requests<3",
+# "rich",
+# ]
+# ///
+
+import requests
+from rich.pretty import pprint
+
+resp = requests.get("https://peps.python.org/api/peps.json")
+data = resp.json()
+pprint([(k, v["title"]) for k, v in data.items()][:10])
+uv will automatically create an environment with the dependencies necessary to run the script, e.g.:
+$ uv run example.py
+[
+│ ('1', 'PEP Purpose and Guidelines'),
+│ ('2', 'Procedure for Adding New Modules'),
+│ ('3', 'Guidelines for Handling Bug Reports'),
+│ ('4', 'Deprecation of Standard Modules'),
+│ ('5', 'Guidelines for Language Evolution'),
+│ ('6', 'Bug Fix Releases'),
+│ ('7', 'Style Guide for C Code'),
+│ ('8', 'Style Guide for Python Code'),
+│ ('9', 'Sample Plaintext PEP Template'),
+│ ('10', 'Voting Guidelines')
+]
+Important
+When using inline script metadata, even if uv run is used in a project, the project's dependencies will be ignored. The --no-project flag is not required.
uv also respects Python version requirements:
+# /// script
+# requires-python = ">=3.12"
+# dependencies = []
+# ///
+
+# Use some syntax added in Python 3.12
+type Point = tuple[float, float]
+print(Point)
+Note
+The dependencies field must be provided even if empty.
uv run will search for and use the required Python version. The Python version will download if it
+is not installed — see the documentation on Python versions for
+more details.
A shebang can be added to make a script executable without using uv run — this makes it easy to
+run scripts that are on your PATH or in the current folder.
For example, create a file called greet with the following contents
Ensure that your script is executable, e.g., with chmod +x greet, then run the script:
Declaration of dependencies is also supported in this context, for example:
+#!/usr/bin/env -S uv run --script
+#
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["httpx"]
+# ///
+
+import httpx
+
+print(httpx.get("https://example.com"))
+If you wish to use an alternative package index to resolve dependencies,
+you can provide the index with the --index option:
This will include the package data in the inline metadata:
+ +If you require authentication to access the package index, then please refer to the +package index documentation.
+uv supports locking dependencies for PEP 723 scripts using the uv.lock file format. Unlike with
+projects, scripts must be explicitly locked using uv lock:
Running uv lock --script will create a .lock file adjacent to the script (e.g.,
+example.py.lock).
Once locked, subsequent operations like uv run --script, uv add --script, uv export --script,
+and uv tree --script will reuse the locked dependencies, updating the lockfile if necessary.
If no such lockfile is present, commands like uv export --script will still function as expected,
+but will not create a lockfile.
In addition to locking dependencies, uv supports an exclude-newer field in the tool.uv section
+of inline script metadata to limit uv to only considering distributions released before a specific
+date. This is useful for improving the reproducibility of your script when run at a later point in
+time.
The date must be specified as an RFC 3339 timestamp
+(e.g., 2006-12-02T02:07:43Z).
# /// script
+# dependencies = [
+# "requests",
+# ]
+# [tool.uv]
+# exclude-newer = "2023-10-16T00:00:00Z"
+# ///
+
+import requests
+
+print(requests.__version__)
+uv allows arbitrary Python versions to be requested on each script invocation, for example:
+ + + +See the Python version request documentation +for more details on requesting Python versions.
+On Windows uv will run your script ending with .pyw extension using pythonw:
from tkinter import Tk, ttk
+
+root = Tk()
+root.title("uv")
+frm = ttk.Frame(root, padding=10)
+frm.grid()
+ttk.Label(frm, text="Hello World").grid(column=0, row=0)
+root.mainloop()
+
Similarly, it works with dependencies as well:
+import sys
+from PyQt5.QtWidgets import QApplication, QWidget, QLabel, QGridLayout
+
+app = QApplication(sys.argv)
+widget = QWidget()
+grid = QGridLayout()
+
+text_label = QLabel()
+text_label.setText("Hello World!")
+grid.addWidget(text_label)
+
+widget.setLayout(grid)
+widget.setGeometry(100, 100, 200, 50)
+widget.setWindowTitle("uv")
+widget.show()
+sys.exit(app.exec_())
+
To learn more about uv run, see the command reference.
Or, read on to learn how to run and install tools with uv.
+ + + + + + + + + + + + + + + + + + + + +Many Python packages provide applications that can be used as tools. uv has specialized support for +easily invoking and installing tools.
+The uvx command invokes a tool without installing it.
For example, to run ruff:
Note
+This is exactly equivalent to:
+ +uvx is provided as an alias for convenience.
Arguments can be provided after the tool name:
+$ uvx pycowsay hello from uv
+
+ -------------
+< hello from uv >
+ -------------
+ \ ^__^
+ \ (oo)\_______
+ (__)\ )\/\
+ ||----w |
+ || ||
+Tools are installed into temporary, isolated environments when using uvx.
Note
+If you are running a tool in a project and the tool requires that
+your project is installed, e.g., when using pytest or mypy, you'll want to use
+uv run instead of uvx. Otherwise, the tool will be run in
+a virtual environment that is isolated from your project.
If your project has a flat structure, e.g., instead of using a src directory for modules,
+the project itself does not need to be installed and uvx is fine. In this case, using
+uv run is only beneficial if you want to pin the version of the tool in the project's
+dependencies.
When uvx ruff is invoked, uv installs the ruff package which provides the ruff command.
+However, sometimes the package and command names differ.
The --from option can be used to invoke a command from a specific package, e.g., http which is
+provided by httpie:
To run a tool at a specific version, use command@<version>:
To run a tool at the latest version, use command@latest:
The --from option can also be used to specify package versions, as above:
Or, to constrain to a range of versions:
+ +Note the @ syntax cannot be used for anything other than an exact version.
The --from option can be used to run a tool with extras:
This can also be combined with version selection:
+ +The --from option can also be used to install from alternative sources.
For example, to pull from git:
+ +You can also pull the latest commit from a specific named branch:
+ +Or pull a specific tag:
+ +Or even a specific commit:
+ +Additional dependencies can be included, e.g., to include mkdocs-material when running mkdocs:
If a tool is used often, it is useful to install it to a persistent environment and add it to the
+PATH instead of invoking uvx repeatedly.
Tip
+uvx is a convenient alias for uv tool run. All of the other commands for interacting with
+tools require the full uv tool prefix.
To install ruff:
When a tool is installed, its executables are placed in a bin directory in the PATH which allows
+the tool to be run without uv. If it's not on the PATH, a warning will be displayed and
+uv tool update-shell can be used to add it to the PATH.
After installing ruff, it should be available:
Unlike uv pip install, installing a tool does not make its modules available in the current
+environment. For example, the following command will fail:
This isolation is important for reducing interactions and conflicts between dependencies of tools, +scripts, and projects.
+Unlike uvx, uv tool install operates on a package and will install all executables provided by
+the tool.
For example, the following will install the http, https, and httpie executables:
Additionally, package versions can be included without --from:
And, similarly, for package sources:
+ +As with uvx, installations can include additional packages:
Multiple related executables can be installed together in the same tool environment, using the
+--with-executables-from flag. For example, the following will install the executables from
+ansible, plus those ones provided by ansible-core and ansible-lint:
To upgrade a tool, use uv tool upgrade:
Tool upgrades will respect the version constraints provided when installing the tool. For example,
+uv tool install ruff >=0.3,<0.4 followed by uv tool upgrade ruff will upgrade Ruff to the latest
+version in the range >=0.3,<0.4.
To instead replace the version constraints, re-install the tool with uv tool install:
To instead upgrade all tools:
+ +By default, uv will use your default Python interpreter (the first it finds) when running,
+installing, or upgrading tools. You can specify the Python interpreter to use with the --python
+option.
For example, to request a specific Python version when running a tool:
+ +Or, when installing a tool:
+ +Or, when upgrading a tool:
+ +For more details on requesting Python versions, see the +Python version concept page.
+Tools also support running
+legacy setuptools scripts.
+These scripts are available via $(uv tool dir)\<tool-name>\Scripts when installed.
Currently only legacy scripts with the .ps1, .cmd, and .bat extensions are supported.
For example, below is an example running a Command Prompt script.
+ +In addition, you don't need to specify the extension. uvx will automatically look for files ending
+in .ps1, .cmd, and .bat in that order of execution on your behalf.
To learn more about managing tools with uv, see the Tools concept page and +the command reference.
+Or, read on to learn how to work on projects.
+ + + + + + + + + + + + + + + + + + + + +An extremely fast Python package and project manager, written in Rust.
+
+
+
+
+
+ Installing Trio's dependencies with a warm cache. +
+ +pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv,
+ and more.pip.curl or pip.uv is backed by Astral, the creators of +Ruff.
+Install uv with our official standalone installer:
+Then, check out the first steps or read on for a brief overview.
+Tip
+uv may also be installed with pip, Homebrew, and more. See all of the methods on the +installation page.
+uv manages project dependencies and environments, with support for lockfiles, workspaces, and more,
+similar to rye or poetry:
$ uv init example
+Initialized project `example` at `/home/user/example`
+
+$ cd example
+
+$ uv add ruff
+Creating virtual environment at: .venv
+Resolved 2 packages in 170ms
+ Built example @ file:///home/user/example
+Prepared 2 packages in 627ms
+Installed 2 packages in 1ms
+ + example==0.1.0 (from file:///home/user/example)
+ + ruff==0.5.4
+
+$ uv run ruff check
+All checks passed!
+
+$ uv lock
+Resolved 2 packages in 0.33ms
+
+$ uv sync
+Resolved 2 packages in 0.70ms
+Audited 1 package in 0.02ms
+See the project guide to get started.
+uv also supports building and publishing projects, even if they're not managed with uv. See the +packaging guide to learn more.
+uv manages dependencies and environments for single-file scripts.
+Create a new script and add inline metadata declaring its dependencies:
+$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
+
+$ uv add --script example.py requests
+Updated `example.py`
+Then, run the script in an isolated virtual environment:
+$ uv run example.py
+Reading inline script metadata from: example.py
+Installed 5 packages in 12ms
+<Response [200]>
+See the scripts guide to get started.
+uv executes and installs command-line tools provided by Python packages, similar to pipx.
Run a tool in an ephemeral environment using uvx (an alias for uv tool run):
$ uvx pycowsay 'hello world!'
+Resolved 1 package in 167ms
+Installed 1 package in 9ms
+ + pycowsay==0.0.0.2
+ """
+
+ ------------
+< hello world! >
+ ------------
+ \ ^__^
+ \ (oo)\_______
+ (__)\ )\/\
+ ||----w |
+ || ||
+Install a tool with uv tool install:
$ uv tool install ruff
+Resolved 1 package in 6ms
+Installed 1 package in 2ms
+ + ruff==0.5.4
+Installed 1 executable: ruff
+
+$ ruff --version
+ruff 0.5.4
+See the tools guide to get started.
+uv installs Python and allows quickly switching between versions.
+Install multiple Python versions:
+$ uv python install 3.10 3.11 3.12
+Searching for Python versions matching: Python 3.10
+Searching for Python versions matching: Python 3.11
+Searching for Python versions matching: Python 3.12
+Installed 3 versions in 3.42s
+ + cpython-3.10.14-macos-aarch64-none
+ + cpython-3.11.9-macos-aarch64-none
+ + cpython-3.12.4-macos-aarch64-none
+Download Python versions as needed:
+$ uv venv --python 3.12.0
+Using CPython 3.12.0
+Creating virtual environment at: .venv
+Activate with: source .venv/bin/activate
+
+$ uv run --python pypy@3.8 -- python
+Python 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30)
+[PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin
+Type "help", "copyright", "credits" or "license" for more information.
+>>>>
+Use a specific Python version in the current directory:
+ +See the installing Python guide to get started.
+uv provides a drop-in replacement for common pip, pip-tools, and virtualenv commands.
uv extends their interfaces with advanced features, such as dependency version overrides, +platform-independent resolutions, reproducible resolutions, alternative resolution strategies, and +more.
+Migrate to uv without changing your existing workflows — and experience a 10-100x speedup — with the
+uv pip interface.
Compile requirements into a platform-independent requirements file:
+$ uv pip compile docs/requirements.in \
+ --universal \
+ --output-file docs/requirements.txt
+Resolved 43 packages in 12ms
+Create a virtual environment:
+$ uv venv
+Using CPython 3.12.3
+Creating virtual environment at: .venv
+Activate with: source .venv/bin/activate
+Install the locked requirements:
+$ uv pip sync docs/requirements.txt
+Resolved 43 packages in 11ms
+Installed 43 packages in 208ms
+ + babel==2.15.0
+ + black==24.4.2
+ + certifi==2024.7.4
+ ...
+See the pip interface documentation to get started.
+See the first steps or jump straight to the +guides to start using uv.
+ + + + + + + + + + + + + + + + + + element
+ const elements = document.querySelectorAll(
+ 'button[data-clipboard-target$="code"]'
+ );
+ const observer = new IntersectionObserver((entries) => {
+ entries.forEach((entry) => {
+ // target in the viewport that have not been patched
+ if (
+ entry.intersectionRatio > 0 &&
+ entry.target.dataset[attr] === undefined
+ ) {
+ entry.target.dataset[attr] = cleanupClipboardText(
+ entry.target.dataset.clipboardTarget
+ );
+ }
+ });
+ });
+
+ elements.forEach((elt) => {
+ observer.observe(elt);
+ });
+}
+
+// Using the document$ observable is particularly important if you are using instant loading since
+// it will not result in a page refresh in the browser
+// See `How to integrate with third-party JavaScript libraries` guideline:
+// https://squidfunk.github.io/mkdocs-material/customization/?h=javascript#additional-javascript
+document$.subscribe(function () {
+ setCopyText();
+
+ // Fix the branding text to make "uv" bold
+ const brandingText = document.querySelector('.md-header__branding-text');
+ if (brandingText && brandingText.textContent === 'uv Documentation') {
+ brandingText.innerHTML = 'uv Documentation';
+ }
+
+ // Reset search modal state on navigation to prevent it from reopening
+ const searchCheckbox = document.getElementById('__search');
+ if (searchCheckbox) {
+ searchCheckbox.checked = false;
+ }
+});
+
+// Use client-side redirects for anchors that have moved.
+// Other redirects should use `redirect_maps` in the `mkdocs.yml` file instead.
+(function () {
+ let redirect_maps = {
+ "concepts/projects/#managing-dependencies":
+ "concepts/projects/dependencies/",
+ "concepts/projects/#project-metadata": "concepts/projects/layout/",
+ "concepts/projects/#defining-entry-points":
+ "concepts/projects/config/#entry-points",
+ "concepts/projects/#build-systems":
+ "concepts/projects/config/#build-systems",
+ "concepts/projects/#configuring-project-packaging":
+ "concepts/projects/config/#project-packaging",
+ "concepts/projects/#creating-projects": "concepts/projects/init/",
+ "concepts/projects/#project-environments":
+ "concepts/projects/layout/#the-project-environment",
+ "concepts/projects/#configuring-the-project-environment-path":
+ "concepts/projects/config/#project-environment-path",
+ "concepts/projects/#project-lockfile":
+ "concepts/projects/layout/#the-lockfile",
+ "concepts/projects/#platform-specific-dependencies":
+ "concepts/projects/dependencies/#platform-specific-dependencies",
+ "concepts/projects/#running-commands": "concepts/projects/run/",
+ "concepts/projects/#building-projects": "concepts/projects/build/",
+ "concepts/projects/#build-isolation":
+ "concepts/projects/config/#build-isolation",
+ "concepts/projects/dependencies/#dependency-specifiers-pep-508":
+ "concepts/projects/dependencies/#dependency-specifiers",
+ "concepts/projects/dependencies/#importing-dependencies":
+ "concepts/projects/dependencies/#importing-dependencies-from-requirements-files",
+ "concepts/projects/layout/#pylock-toml":
+ "concepts/projects/layout/#relationship-to-pylock-toml",
+ "concepts/projects/run/#legacy-windows-scripts":
+ "concepts/projects/run/#legacy-scripts-on-windows",
+ "concepts/projects/sync/#checking-if-the-lockfile-is-up-to-date":
+ "concepts/projects/sync/#checking-the-lockfile",
+ "concepts/authentication/#git-authentication":
+ "concepts/authentication/git/",
+ "concepts/authentication/#git-credential-helpers":
+ "concepts/authentication/git/#git-credential-helpers",
+ "concepts/authentication/#http-authentication":
+ "concepts/authentication/http/",
+ "concepts/authentication/#using-netrc-files":
+ "concepts/authentication/http/#using-netrc-files",
+ "concepts/authentication/#using-the-keyring":
+ "concepts/authentication/http/#using-the-keyring",
+ "concepts/authentication/#authentication-with-alternative-package-indexes":
+ "concepts/authentication/http/#authentication-with-alternative-package-indexes",
+ "concepts/authentication/#custom-ca-certificates":
+ "concepts/authentication/certificates/",
+ "concepts/authentication/#hugging-face-support":
+ "concepts/authentication/third-party/#hugging-face-support",
+ };
+
+ // The prefix for the site, see `site_dir` in `mkdocs.yml`
+ let site_dir = "uv";
+
+ function get_path() {
+ var path = window.location.pathname;
+
+ // Trim the site prefix
+ if (path.startsWith("/" + site_dir + "/")) {
+ path = path.slice(site_dir.length + 2);
+ }
+
+ // Always include a trailing `/`
+ if (!path.endsWith("/")) {
+ path = path + "/";
+ }
+
+ // Check for an anchor
+ var anchor = window.location.hash.substring(1);
+ if (!anchor) {
+ return path;
+ }
+
+ return path + "#" + anchor;
+ }
+
+ let path = get_path();
+ if (path && redirect_maps.hasOwnProperty(path)) {
+ window.location.replace("/" + site_dir + "/" + redirect_maps[path]);
+ }
+})();
diff --git a/site/uv-next/pip/compatibility/index.html b/site/uv-next/pip/compatibility/index.html
new file mode 100644
index 000000000..0c9ed7c35
--- /dev/null
+++ b/site/uv-next/pip/compatibility/index.html
@@ -0,0 +1,4366 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Compatibility with pip and pip-tools | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Compatibility with pip and pip-tools
+uv is designed as a drop-in replacement for common pip and pip-tools workflows.
+Informally, the intent is such that existing pip and pip-tools users can switch to uv without
+making meaningful changes to their packaging workflows; and, in most cases, swapping out
+pip install for uv pip install should "just work".
+However, uv is not intended to be an exact clone of pip, and the further you stray from common
+pip workflows, the more likely you are to encounter differences in behavior. In some cases, those
+differences may be known and intentional; in others, they may be the result of implementation
+details; and in others, they may be bugs.
+This document outlines the known differences between uv and pip, along with rationale,
+workarounds, and a statement of intent for compatibility in the future.
+Configuration files and environment variables
+uv does not read configuration files or environment variables that are specific to pip, like
+pip.conf or PIP_INDEX_URL.
+Reading configuration files and environment variables intended for other tools has a number of
+drawbacks:
+
+- It requires bug-for-bug compatibility with the target tool, since users end up relying on bugs in
+ the format, the parser, etc.
+- If the target tool changes the format in some way, uv is then locked-in to changing it in
+ equivalent ways.
+- If that configuration is versioned in some way, uv would need to know which version of the
+ target tool the user is expecting to use.
+- It prevents uv from introducing any settings or configuration that don't exist in the target
+ tool, since otherwise
pip.conf (or similar) would no longer be usable with pip.
+- It can lead to user confusion, since uv would be reading settings that don't actually affect its
+ behavior, and many users may not expect uv to read configuration files intended for other
+ tools.
+
+Instead, uv supports its own environment variables, like UV_INDEX_URL. uv also supports persistent
+configuration in a uv.toml file or a [tool.uv.pip] section of pyproject.toml. For more
+information, see Configuration files.
+Pre-release compatibility
+By default, uv will accept pre-release versions during dependency resolution in two cases:
+
+- If the package is a direct dependency, and its version markers include a pre-release specifier
+ (e.g.,
flask>=2.0.0rc1).
+- If all published versions of a package are pre-releases.
+
+If dependency resolution fails due to a transitive pre-release, uv will prompt the user to re-run
+with --prerelease allow, to allow pre-releases for all dependencies.
+Alternatively, you can add the transitive dependency to your requirements.in file with pre-release
+specifier (e.g., flask>=2.0.0rc1) to opt in to pre-release support for that specific dependency.
+In sum, uv needs to know upfront whether the resolver should accept pre-releases for a given
+package. pip, meanwhile, may respect pre-release identifiers in transitive dependencies
+depending on the order in which the resolver encounters the relevant specifiers
+(#1641).
+Pre-releases are
+notoriously difficult to
+model, and are a frequent source of bugs in packaging tools. Even pip, which is viewed as a
+reference implementation, has a number of open questions around pre-release handling
+(#12469,
+#12470,
+#40505, etc.).
+uv's pre-release handling is intentionally limited and intentionally requires user opt-in for
+pre-releases, to ensure correctness.
+In the future, uv may support pre-release identifiers in transitive dependencies. However, it's
+likely contingent on evolution in the Python packaging specifications. The existing PEPs
+do not cover "dependency resolution"
+and are instead focused on behavior for a single version specifier. As such, there are unresolved
+questions around the correct and intended behavior for pre-releases in the packaging ecosystem more
+broadly.
+Packages that exist on multiple indexes
+In both uv and pip, users can specify multiple package indexes from which to search for the
+available versions of a given package. However, uv and pip differ in how they handle packages that
+exist on multiple indexes.
+For example, imagine that a company publishes an internal version of requests on a private index
+(--extra-index-url), but also allows installing packages from PyPI by default. In this case, the
+private requests would conflict with the public requests
+on PyPI.
+When uv searches for a package across multiple indexes, it will iterate over the indexes in order
+(preferring the --extra-index-url over the default index), and stop searching as soon as it finds
+a match. This means that if a package exists on multiple indexes, uv will limit its candidate
+versions to those present in the first index that contains the package.
+pip, meanwhile, will combine the candidate versions from all indexes, and select the best version
+from the combined set, though it makes
+no guarantees around the order in
+which it searches indexes, and expects that packages are unique up to name and version, even across
+indexes.
+uv's behavior is such that if a package exists on an internal index, it should always be installed
+from the internal index, and never from PyPI. The intent is to prevent "dependency confusion"
+attacks, in which an attacker publishes a malicious package on PyPI with the same name as an
+internal package, thus causing the malicious package to be installed instead of the internal
+package. See, for example,
+the torchtriton attack from
+December 2022.
+As of v0.1.39, users can opt in to pip-style behavior for multiple indexes via the
+--index-strategy command-line option, or the UV_INDEX_STRATEGY environment variable, which
+supports the following values:
+
+first-index (default): Search for each package across all indexes, limiting the candidate
+ versions to those present in the first index that contains the package, prioritizing the
+ --extra-index-url indexes over the default index URL.unsafe-first-match: Search for each package across all indexes, but prefer the first index with
+ a compatible version, even if newer versions are available on other indexes.unsafe-best-match: Search for each package across all indexes, and select the best version from
+ the combined set of candidate versions.
+While unsafe-best-match is the closest to pip's behavior, it exposes users to the risk of
+"dependency confusion" attacks.
+uv also supports pinning packages to dedicated indexes (see:
+Indexes), such that a given package is
+always installed from a specific index.
+PEP 517 build isolation
+uv uses PEP 517 build isolation by default (akin to
+pip install --use-pep517), following pypa/build and in anticipation of pip defaulting to PEP
+517 builds in the future (pypa/pip#9175).
+If a package fails to install due to a missing build-time dependency, try using a newer version of
+the package; if the problem persists, consider filing an issue with the package maintainer,
+requesting that they update the packaging setup to declare the correct PEP 517 build-time
+dependencies.
+As an escape hatch, you can preinstall a package's build dependencies, then run uv pip install
+with --no-build-isolation, as in:
+
+For a list of packages that are known to fail under PEP 517 build isolation, see
+#2252.
+Transitive URL dependencies
+While uv includes first-class support for URL dependencies (e.g., ruff @ https://...), it differs
+from pip in its handling of transitive URL dependencies in two ways.
+First, uv makes the assumption that non-URL dependencies do not introduce URL dependencies into the
+resolution. In other words, it assumes that dependencies fetched from a registry do not themselves
+depend on URLs. If a non-URL dependency does introduce a URL dependency, uv will reject the URL
+dependency during resolution. (Note that PyPI does not allow published packages to depend on URL
+dependencies; other registries may be more permissive.)
+Second, if a constraint (--constraint) or override (--override) is defined using a direct URL
+dependency, and the constrained package has a direct URL dependency of its own, uv may reject that
+transitive direct URL dependency during resolution, if the URL isn't referenced elsewhere in the set
+of input requirements.
+If uv rejects a transitive URL dependency, the best course of action is to provide the URL
+dependency as a direct dependency in the relevant pyproject.toml or requirement.in file, as the
+above constraints do not apply to direct dependencies.
+Virtual environments by default
+uv pip install and uv pip sync are designed to work with virtual environments by default.
+Specifically, uv will always install packages into the currently active virtual environment, or
+search for a virtual environment named .venv in the current directory or any parent directory
+(even if it is not activated).
+This differs from pip, which will install packages into a global environment if no virtual
+environment is active, and will not search for inactive virtual environments.
+In uv, you can install into non-virtual environments by providing a path to a Python executable via
+the --python /path/to/python option, or via the --system flag, which installs into the first
+Python interpreter found on the PATH, like pip.
+In other words, uv inverts the default, requiring explicit opt-in to installing into the system
+Python, which can lead to breakages and other complications, and should only be done in limited
+circumstances.
+For more, see
+"Using arbitrary Python environments".
+Resolution strategy
+For a given set of dependency specifiers, it's often the case that there is no single "correct" set
+of packages to install. Instead, there are many valid sets of packages that satisfy the specifiers.
+Neither pip nor uv make any guarantees about the exact set of packages that will be installed;
+only that the resolution will be consistent, deterministic, and compliant with the specifiers. As
+such, in some cases, pip and uv will yield different resolutions; however, both resolutions
+should be equally valid.
+For example, consider:
+
+At time of writing, the most recent starlette version is 0.37.2, and the most recent fastapi
+version is 0.110.0. However, fastapi==0.110.0 also depends on starlette, and introduces an
+upper bound: starlette>=0.36.3,<0.37.0.
+If a resolver prioritizes including the most recent version of starlette, it would need to use an
+older version of fastapi that excludes the upper bound on starlette. In practice, this requires
+falling back to fastapi==0.1.17:
+requirements.txt# This file was autogenerated by uv via the following command:
+# uv pip compile requirements.in
+annotated-types==0.6.0
+ # via pydantic
+anyio==4.3.0
+ # via starlette
+fastapi==0.1.17
+idna==3.6
+ # via anyio
+pydantic==2.6.3
+ # via fastapi
+pydantic-core==2.16.3
+ # via pydantic
+sniffio==1.3.1
+ # via anyio
+starlette==0.37.2
+ # via fastapi
+typing-extensions==4.10.0
+ # via
+ # pydantic
+ # pydantic-core
+
+Alternatively, if a resolver prioritizes including the most recent version of fastapi, it would
+need to use an older version of starlette that satisfies the upper bound. In practice, this
+requires falling back to starlette==0.36.3:
+requirements.txt# This file was autogenerated by uv via the following command:
+# uv pip compile requirements.in
+annotated-types==0.6.0
+ # via pydantic
+anyio==4.3.0
+ # via starlette
+fastapi==0.110.0
+idna==3.6
+ # via anyio
+pydantic==2.6.3
+ # via fastapi
+pydantic-core==2.16.3
+ # via pydantic
+sniffio==1.3.1
+ # via anyio
+starlette==0.36.3
+ # via fastapi
+typing-extensions==4.10.0
+ # via
+ # fastapi
+ # pydantic
+ # pydantic-core
+
+When uv resolutions differ from pip in undesirable ways, it's often a sign that the specifiers are
+too loose, and that the user should consider tightening them. For example, in the case of
+starlette and fastapi, the user could require fastapi>=0.110.0.
+pip check
+At present, uv pip check will surface the following diagnostics:
+
+- A package has no
METADATA file, or the METADATA file can't be parsed.
+- A package has a
Requires-Python that doesn't match the Python version of the running
+ interpreter.
+- A package has a dependency on a package that isn't installed.
+- A package has a dependency on a package that's installed, but at an incompatible version.
+- Multiple versions of a package are installed in the virtual environment.
+
+In some cases, uv pip check will surface diagnostics that pip check does not, and vice versa.
+For example, unlike uv pip check, pip check will not warn when multiple versions of a package
+are installed in the current environment.
+--user and the user install scheme
+uv does not support the --user flag, which installs packages based on the user install scheme.
+Instead, we recommend the use of virtual environments to isolate package installations.
+Additionally, pip will fall back to the user install scheme if it detects that the user does not
+have write permissions to the target directory, as is the case on some systems when installing into
+the system Python. uv does not implement any such fallback.
+For more, see #2077.
+--only-binary enforcement
+The --only-binary argument is used to restrict installation to pre-built binary distributions.
+When --only-binary :all: is provided, both pip and uv will refuse to build source distributions
+from PyPI and other registries.
+However, when a dependency is provided as a direct URL (e.g., uv pip install https://...), pip
+does not enforce --only-binary, and will build source distributions for all such packages.
+uv, meanwhile, does enforce --only-binary for direct URL dependencies, with one exception: given
+uv pip install https://... --only-binary flask, uv will build the source distribution at the
+given URL if it cannot infer the package name ahead of time, since uv can't determine whether the
+package is "allowed" in such cases without building its metadata.
+Both pip and uv allow editables requirements to be built and installed even when --only-binary is
+provided. For example, uv pip install -e . --only-binary :all: is allowed.
+--no-binary enforcement
+The --no-binary argument is used to restrict installation to source distributions. When
+--no-binary is provided, uv will refuse to install pre-built binary distributions, but will
+reuse any binary distributions that are already present in the local cache.
+Additionally, and in contrast to pip, uv's resolver will still read metadata from pre-built binary
+distributions when --no-binary is provided.
+manylinux_compatible enforcement
+PEP 600 describes a mechanism through which
+Python distributors can opt out of manylinux compatibility by defining a manylinux_compatible
+function on the _manylinux standard library module.
+uv respects manylinux_compatible, but only tests against the current glibc version, and applies
+the return value of manylinux_compatible globally.
+In other words, if manylinux_compatible returns True, uv will treat the system as
+manylinux-compatible; if it returns False, uv will treat the system as manylinux-incompatible,
+without calling manylinux_compatible for every glibc version.
+This approach is not a complete implementation of the spec, but is compatible with common blanket
+manylinux_compatible implementations like
+no-manylinux:
+from __future__ import annotations
+manylinux1_compatible = False
+manylinux2010_compatible = False
+manylinux2014_compatible = False
+
+
+def manylinux_compatible(*_, **__): # PEP 600
+ return False
+
+Bytecode compilation
+Unlike pip, uv does not compile .py files to .pyc files during installation by default (i.e.,
+uv does not create or populate __pycache__ directories). To enable bytecode compilation during
+installs, pass the --compile-bytecode flag to uv pip install or uv pip sync, or set the
+UV_COMPILE_BYTECODE environment variable to 1.
+Skipping bytecode compilation can be undesirable in workflows; for example, we recommend enabling
+bytecode compilation in Docker builds to improve startup times
+(at the cost of increased build times).
+As bytecode compilation suppresses various warnings issued by the Python interpreter, in rare cases
+you may seen SyntaxWarning or DeprecationWarning messages when running Python code that was
+installed with uv that do not appear when using pip. These are valid warnings, but are typically
+hidden by the bytecode compilation process, and can either be ignored, fixed upstream, or similarly
+suppressed by enabling bytecode compilation in uv.
+Strictness and spec enforcement
+uv tends to be stricter than pip, and will often reject packages that pip would install. For
+example, uv rejects HTML indexes with invalid URL fragments (see:
+PEP 503), while pip will ignore such fragments.
+In some cases, uv implements lenient behavior for popular packages that are known to have specific
+spec compliance issues.
+If uv rejects a package that pip would install due to a spec violation, the best course of action
+is to first attempt to install a newer version of the package; and, if that fails, to report the
+issue to the package maintainer.
+pip command-line options and subcommands
+uv does not support the complete set of pip's command-line options and subcommands, although it
+does support a large subset.
+Missing options and subcommands are prioritized based on user demand and the complexity of the
+implementation, and tend to be tracked in individual issues. For example:
+
+--trusted-host--user
+If you encounter a missing option or subcommand, please search the issue tracker to see if it has
+already been reported, and if not, consider opening a new issue. Feel free to upvote any existing
+issues to convey your interest.
+Registry authentication
+uv does not support pip's auto or import options for --keyring-provider. At present, only
+the subprocess option is supported.
+Unlike pip, uv does not enable keyring authentication by default.
+Unlike pip, uv does not wait until a request returns an HTTP 401 before searching for
+authentication. uv attaches authentication to all requests for hosts with credentials available.
+egg support
+uv does not support features that are considered legacy or deprecated in pip. For example, uv does
+not support .egg-style distributions.
+However, uv does have partial support for (1) .egg-info-style distributions (which are
+occasionally found in Docker images and Conda environments) and (2) legacy editable
+.egg-link-style distributions.
+Specifically, uv does not support installing new .egg-info- or .egg-link-style distributions,
+but will respect any such existing distributions during resolution, list them with uv pip list and
+uv pip freeze, and uninstall them with uv pip uninstall.
+Build constraints
+When constraints are provided via --constraint (or UV_CONSTRAINT), uv will not apply the
+constraints when resolving build dependencies (i.e., to build a source distribution). Instead, build
+constraints should be provided via the dedicated --build-constraint (or UV_BUILD_CONSTRAINT)
+setting.
+pip, meanwhile, applies constraints to build dependencies when specified via PIP_CONSTRAINT, but
+not when provided via --constraint on the command line.
+For example, to ensure that setuptools 60.0.0 is used to build any packages with a build
+dependency on setuptools, use --build-constraint, rather than --constraint.
+pip compile defaults
+There are a few small but notable differences in the default behaviors of pip compile and
+pip-tools.
+By default, uv does not write the compiled requirements to an output file. Instead, uv requires that
+the user specify an output file explicitly with the -o or --output-file option.
+By default, uv strips extras when outputting the compiled requirements. In other words, uv defaults
+to --strip-extras, while pip-compile defaults to --no-strip-extras. pip-compile is scheduled
+to change this default in the next major release (v8.0.0), at which point both tools will default to
+--strip-extras. To retain extras with uv, pass the --no-strip-extras flag to uv pip compile.
+By default, uv does not write any index URLs to the output file, while pip-compile outputs any
+--index-url or --extra-index-url that does not match the default (PyPI). To include index URLs
+in the output file, pass the --emit-index-url flag to uv pip compile. Unlike pip-compile, uv
+will include all index URLs when --emit-index-url is passed, including the default index URL.
+requires-python upper bounds
+When evaluating requires-python ranges for dependencies, uv only considers lower bounds and
+ignores upper bounds entirely. For example, >=3.8, <4 is treated as >=3.8. Respecting upper
+bounds on requires-python often leads to formally correct but practically incorrect resolutions,
+as, e.g., resolvers will backtrack to the first published version that omits the upper bound (see:
+Requires-Python upper limits).
+requires-python specifiers
+When evaluating Python versions against requires-python specifiers, uv truncates the candidate
+version to the major, minor, and patch components, ignoring (e.g.) pre-release and post-release
+identifiers.
+For example, a project that declares requires-python: >=3.13 will accept Python 3.13.0b1. While
+3.13.0b1 is not strictly greater than 3.13, it is greater than 3.13 when the pre-release identifier
+is omitted.
+While this is not strictly compliant with PEP 440, it is
+consistent with
+pip.
+Package priority
+There are usually many possible solutions given a set of requirements, and a resolver must choose
+between them. uv's resolver and pip's resolver have a different set of package priorities. While
+both resolvers use the user-provided order as one of their priorities, pip has additional
+priorities
+that uv does not have. Hence, uv is more likely to be affected by a change in user order than pip
+is.
+For example, uv pip install foo bar prioritizes newer versions of foo over bar and could
+result in a different resolution than uv pip install bar foo. Similarly, this behavior applies to
+the ordering of requirements in input files for uv pip compile.
+Wheel filename and metadata validation
+By default, uv will reject wheels whose filenames are inconsistent with the wheel metadata inside
+the file. For example, a wheel named foo-1.0.0-py3-none-any.whl that contains metadata indicating
+the version is 1.0.1 will be rejected by uv, but accepted by pip.
+To force uv to accept such wheels, set UV_SKIP_WHEEL_FILENAME_CHECK=1 in the environment.
+Package name normalization
+By default, uv normalizes package names to match their
+PEP 503-compliant forms
+and uses those normalized names in all output contexts. This differs from pip, which tends to
+preserve the verbatim package name as published on the registry.
+For example, uv pip list displays normalized packages names (e.g., docstring-parser), while
+pip list displays non-normalized package names (e.g., docstring_parser):
+(venv) $ diff --side-by-side <(pip list) <(uv pip list)
+Package Version Package Version
+---------------- ------- ---------------- -------
+docstring_parser 0.16 | docstring-parser 0.16
+jaraco.classes 3.4.0 | jaraco-classes 3.4.0
+more-itertools 10.7.0 more-itertools 10.7.0
+pip 25.1 pip 25.1
+PyMuPDFb 1.24.10 | pymupdfb 1.24.10
+PyPDF2 3.0.1 | pypdf2 3.0.1
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/pip/compile/index.html b/site/uv-next/pip/compile/index.html
new file mode 100644
index 000000000..ea243a77b
--- /dev/null
+++ b/site/uv-next/pip/compile/index.html
@@ -0,0 +1,3711 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Locking environments | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Locking environments
+Locking is to take a dependency, e.g., ruff, and write an exact version to use to a file. When
+working with many dependencies, it is useful to lock the exact versions so the environment can be
+reproduced. Without locking, the versions of dependencies could change over time, when using a
+different tool, or across platforms.
+Locking requirements
+uv allows dependencies to be locked in the requirements.txt format. It is recommended to use the
+standard pyproject.toml to define dependencies, but other dependency formats are supported as
+well. See the documentation on declaring dependencies for more details on how to
+define dependencies.
+To lock dependencies declared in a pyproject.toml:
+
+Note by default the uv pip compile output is just displayed and --output-file / -o argument is
+needed to write to a file.
+To lock dependencies declared in a requirements.in:
+
+To lock dependencies declared in multiple files:
+
+uv also supports legacy setup.py and setup.cfg formats. To lock dependencies declared in a
+setup.py:
+
+To lock dependencies from stdin, use -:
+
+To lock with optional dependencies enabled, e.g., the "foo" extra:
+
+To lock with all optional dependencies enabled:
+
+Note extras are not supported with the requirements.in format.
+To lock a dependency group in the current project directory's pyproject.toml, for example the
+group foo:
+
+
+Important
+A --group flag has to be added to pip-tools' pip compile, although they're considering it. We expect to support whatever syntax and semantics they adopt.
+
+To specify the project directory where groups should be sourced from:
+
+Alternatively, you can specify a path to a pyproject.toml for each group:
+
+
+Note
+--group flags do not apply to other specified sources. For instance,
+uv pip compile some/path/pyproject.toml --group foo sources foo
+from ./pyproject.toml and not some/path/pyproject.toml.
+
+Upgrading requirements
+When using an output file, uv will consider the versions pinned in an existing output file. If a
+dependency is pinned it will not be upgraded on a subsequent compile run. For example:
+$ echo "ruff==0.3.0" > requirements.txt
+$ echo "ruff" | uv pip compile - -o requirements.txt
+# This file was autogenerated by uv via the following command:
+# uv pip compile - -o requirements.txt
+ruff==0.3.0
+
+To upgrade a dependency, use the --upgrade-package flag:
+
+To upgrade all dependencies, there is an --upgrade flag.
+Syncing an environment
+Dependencies can be installed directly from their definition files or from compiled
+requirements.txt files with uv pip install. See the documentation on
+installing packages from files for more details.
+When installing with uv pip install, packages that are already installed will not be removed
+unless they conflict with the lockfile. This means that the environment can have dependencies that
+aren't declared in the lockfile, which isn't great for reproducibility. To ensure the environment
+exactly matches the lockfile, use uv pip sync instead.
+To sync an environment with a requirements.txt file:
+
+To sync an environment with a PEP 751 pylock.toml file:
+
+Adding constraints
+Constraints files are requirements.txt-like files that only control the version of a requirement
+that's installed. However, including a package in a constraints file will not trigger the
+installation of that package. Constraints can be used to add bounds to dependencies that are not
+dependencies of the current project.
+To define a constraint, define a bound for a package:
+
+To use a constraints file:
+
+Note that multiple constraints can be defined in each file and multiple files can be used.
+uv will also read constraint-dependencies from the pyproject.toml at the workspace root, and
+append them to those specified in the constraints file.
+Adding build constraints
+Similar to constraints, but specifically for build-time dependencies, including those required
+when building runtime dependencies.
+Build constraint files are requirements.txt-like files that only control the version of a
+build-time requirement. However, including a package in a build constraints file will not trigger
+its installation at build time; instead, constraints apply only when the package is required as a
+direct or transitive build-time dependency. Build constraints can be used to add bounds to
+dependencies that are not explicitly declared as build-time dependencies of the current project.
+For example, if a package defines its build dependencies as follows:
+
+Build constraints could be used to ensure that a specific version of setuptools is used for every
+package in the workspace:
+
+uv will also read build-constraint-dependencies from the pyproject.toml at the workspace root,
+and append them to those specified in the build constraints file.
+Overriding dependency versions
+Overrides files are requirements.txt-like files that force a specific version of a requirement to
+be installed, regardless of the requirements declared by any constituent package, and regardless of
+whether this would be considered an invalid resolution.
+While constraints are additive, in that they're combined with the requirements of the constituent
+packages, overrides are absolute, in that they completely replace the requirements of the
+constituent packages.
+Overrides are most often used to remove upper bounds from a transitive dependency. For example, if
+a requires c>=1.0,<2.0 and b requires c>=2.0 and the current project requires a and b
+then the dependencies cannot be resolved.
+To define an override, define the new requirement for the problematic package:
+
+To use an overrides file:
+
+Now, resolution can succeed. However, note that if a is correct that it does not support
+c>=2.0 then a runtime error will likely be encountered when using the packages.
+Note that multiple overrides can be defined in each file and multiple files can be used.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/pip/dependencies/index.html b/site/uv-next/pip/dependencies/index.html
new file mode 100644
index 000000000..d3c2abee8
--- /dev/null
+++ b/site/uv-next/pip/dependencies/index.html
@@ -0,0 +1,3525 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Declaring dependencies | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Declaring dependencies
+It is best practice to declare dependencies in a static file instead of modifying environments with
+ad-hoc installations. Once dependencies are defined, they can be locked to create a
+consistent, reproducible environment.
+Using pyproject.toml
+The pyproject.toml file is the Python standard for defining configuration for a project.
+To define project dependencies in a pyproject.toml file:
+
+To define optional dependencies in a pyproject.toml file:
+
+Each of the keys defines an "extra", which can be installed using the --extra and --all-extras
+flags or package[<extra>] syntax. See the documentation on
+installing packages for more details.
+See the official
+pyproject.toml guide for
+more details on getting started with a pyproject.toml.
+Using requirements.in
+It is also common to use a lightweight requirements.txt format to declare the dependencies for the
+project. Each requirement is defined on its own line. Commonly, this file is called
+requirements.in to distinguish it from requirements.txt which is used for the locked
+dependencies.
+To define dependencies in a requirements.in file:
+
+Optional dependencies groups are not supported in this format.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/pip/environments/index.html b/site/uv-next/pip/environments/index.html
new file mode 100644
index 000000000..d642448c4
--- /dev/null
+++ b/site/uv-next/pip/environments/index.html
@@ -0,0 +1,3671 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Using Python environments | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Using Python environments
+Each Python installation has an environment that is active when Python is used. Packages can be
+installed into an environment to make their modules available from your Python scripts. Generally,
+it is considered best practice not to modify a Python installation's environment. This is especially
+important for Python installations that come with the operating system which often manage the
+packages themselves. A virtual environment is a lightweight way to isolate packages from a Python
+installation's environment. Unlike pip, uv requires using a virtual environment by default.
+Creating a virtual environment
+uv supports creating virtual environments, e.g., to create a virtual environment at .venv:
+
+A specific name or path can be specified, e.g., to create a virtual environment at my-name:
+
+A Python version can be requested, e.g., to create a virtual environment with Python 3.11:
+
+Note this requires the requested Python version to be available on the system. However, if
+unavailable, uv will download Python for you. See the
+Python version documentation for more details.
+Using a virtual environment
+When using the default virtual environment name, uv will automatically find and use the virtual
+environment during subsequent invocations.
+
+The virtual environment can be "activated" to make its packages available:
+
+
+Note
+The default activation script on Unix is for POSIX compliant shells like sh, bash, or zsh.
+There are additional activation scripts for common alternative shells.
+
+
+Deactivating an environment
+To exit a virtual environment, use the deactivate command:
+
+Using arbitrary Python environments
+Since uv has no dependency on Python, it can install into virtual environments other than its own.
+For example, setting VIRTUAL_ENV=/path/to/venv will cause uv to install into /path/to/venv,
+regardless of where uv is installed. Note that if VIRTUAL_ENV is set to a directory that is
+not a PEP 405 compliant virtual environment,
+it will be ignored.
+uv can also install into arbitrary, even non-virtual environments, with the --python argument
+provided to uv pip sync or uv pip install. For example,
+uv pip install --python /path/to/python will install into the environment linked to the
+/path/to/python interpreter.
+For convenience, uv pip install --system will install into the system Python environment. Using
+--system is roughly equivalent to uv pip install --python $(which python), but note that
+executables that are linked to virtual environments will be skipped. Although we generally recommend
+using virtual environments for dependency management, --system is appropriate in continuous
+integration and containerized environments.
+The --system flag is also used to opt in to mutating system environments. For example, the
+--python argument can be used to request a Python version (e.g., --python 3.12), and uv will
+search for an interpreter that meets the request. If uv finds a system interpreter (e.g.,
+/usr/lib/python3.12), then the --system flag is required to allow modification of this
+non-virtual Python environment. Without the --system flag, uv will ignore any interpreters that
+are not in virtual environments. Conversely, when the --system flag is provided, uv will ignore
+any interpreters that are in virtual environments.
+Installing into system Python across platforms and distributions is notoriously difficult. uv
+supports the common cases, but will not work in all cases. For example, installing into system
+Python on Debian prior to Python 3.10 is unsupported due to the
+distribution's patching of distutils (but not sysconfig).
+While we always recommend the use of virtual environments, uv considers them to be required in these
+non-standard environments.
+If uv is installed in a Python environment, e.g., with pip, it can still be used to modify other
+environments. However, when invoked with python -m uv, uv will default to using the parent
+interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for
+general usage.
+uv itself does not depend on Python, but it does need to locate a Python environment to (1) install
+dependencies into the environment and (2) build source distributions.
+Discovery of Python environments
+When running a command that mutates an environment such as uv pip sync or uv pip install, uv
+will search for a virtual environment in the following order:
+
+- An activated virtual environment based on the
VIRTUAL_ENV environment variable.
+- An activated Conda environment based on the
CONDA_PREFIX environment variable.
+- A virtual environment at
.venv in the current directory, or in the nearest parent directory.
+
+If no virtual environment is found, uv will prompt the user to create one in the current directory
+via uv venv.
+If the --system flag is included, uv will skip virtual environments search for an installed Python
+version. Similarly, when running a command that does not mutate the environment such as
+uv pip compile, uv does not require a virtual environment — however, a Python interpreter is
+still required. See the documentation on
+Python discovery for details on the
+discovery of installed Python versions.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/pip/index.html b/site/uv-next/pip/index.html
new file mode 100644
index 000000000..c14d29643
--- /dev/null
+++ b/site/uv-next/pip/index.html
@@ -0,0 +1,3412 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+The pip interface | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+The pip interface
+uv provides a drop-in replacement for common pip, pip-tools, and virtualenv commands. These
+commands work directly with the virtual environment, in contrast to uv's primary interfaces where
+the virtual environment is managed automatically. The uv pip interface exposes the speed and
+functionality of uv to power users and projects that are not ready to transition away from pip and
+pip-tools.
+The following sections discuss the basics of using uv pip:
+
+- Creating and using environments
+- Installing and managing packages
+- Inspecting environments and packages
+- Declaring package dependencies
+- Locking and syncing environments
+
+Please note these commands do not exactly implement the interfaces and behavior of the tools they
+are based on. The further you stray from common workflows, the more likely you are to encounter
+differences. Consult the pip-compatibility guide for details.
+
+Important
+uv does not rely on or invoke pip. The pip interface is named as such to highlight its dedicated
+purpose of providing low-level commands that match pip's interface and to separate it from the
+rest of uv's commands which operate at a higher level of abstraction.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/pip/inspection/index.html b/site/uv-next/pip/inspection/index.html
new file mode 100644
index 000000000..47752d949
--- /dev/null
+++ b/site/uv-next/pip/inspection/index.html
@@ -0,0 +1,3533 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Inspecting environments | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Inspecting environments
+Listing installed packages
+To list all the packages in the environment:
+
+To list the packages in a JSON format:
+
+To list all the packages in the environment in a requirements.txt format:
+
+Inspecting a package
+To show information about an installed package, e.g., numpy:
+
+Multiple packages can be inspected at once.
+Verifying an environment
+It is possible to install packages with conflicting requirements into an environment if installed in
+multiple steps.
+To check for conflicts or missing dependencies in the environment:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/pip/packages/index.html b/site/uv-next/pip/packages/index.html
new file mode 100644
index 000000000..a6f506b57
--- /dev/null
+++ b/site/uv-next/pip/packages/index.html
@@ -0,0 +1,3615 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Managing packages | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Managing packages
+Installing a package
+To install a package into the virtual environment, e.g., Flask:
+
+To install a package with optional dependencies enabled, e.g., Flask with the "dotenv" extra:
+
+To install multiple packages, e.g., Flask and Ruff:
+
+To install a package with a constraint, e.g., Ruff v0.2.0 or newer:
+
+To install a package at a specific version, e.g., Ruff v0.3.0:
+
+To install a package from the disk:
+
+To install a package from GitHub:
+
+To install a package from GitHub at a specific reference:
+$ # Install a tag
+$ uv pip install "git+https://github.com/astral-sh/ruff@v0.2.0"
+
+$ # Install a commit
+$ uv pip install "git+https://github.com/astral-sh/ruff@1fadefa67b26508cc59cf38e6130bde2243c929d"
+
+$ # Install a branch
+$ uv pip install "git+https://github.com/astral-sh/ruff@main"
+
+See the Git authentication documentation for installation from
+a private repository.
+Editable packages
+Editable packages do not need to be reinstalled for changes to their source code to be active.
+To install the current project as an editable package
+
+To install a project in another directory as an editable package:
+
+Installing packages from files
+Multiple packages can be installed at once from standard file formats.
+Install from a requirements.txt file:
+
+See the uv pip compile documentation for more information on requirements.txt
+files.
+Install from a pyproject.toml file:
+
+Install from a pyproject.toml file with optional dependencies enabled, e.g., the "foo" extra:
+
+Install from a pyproject.toml file with all optional dependencies enabled:
+
+To install dependency groups in the current project directory's pyproject.toml, for example the
+group foo:
+
+To specify the project directory where groups should be sourced from:
+
+Alternatively, you can specify a path to a pyproject.toml for each group:
+
+
+Note
+As in pip, --group flags do not apply to other sources specified with flags like -r or -e.
+For instance, uv pip install -r some/path/pyproject.toml --group foo sources foo
+from ./pyproject.toml and not some/path/pyproject.toml.
+
+Uninstalling a package
+To uninstall a package, e.g., Flask:
+
+To uninstall multiple packages, e.g., Flask and Ruff:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/benchmarks/index.html b/site/uv-next/reference/benchmarks/index.html
new file mode 100644
index 000000000..8492d449b
--- /dev/null
+++ b/site/uv-next/reference/benchmarks/index.html
@@ -0,0 +1,3384 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Benchmarks | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Benchmarks
+uv's performance is continually benchmarked against previous releases, and regularly compared to
+other tools in the space, like pip and Poetry.
+The latest benchmarks and details on the benchmarking process can be found in the
+GitHub repository.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/cli/index.html b/site/uv-next/reference/cli/index.html
new file mode 100644
index 000000000..6c70b3dbf
--- /dev/null
+++ b/site/uv-next/reference/cli/index.html
@@ -0,0 +1,10816 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+CLI Reference | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+CLI Reference
+uv
+An extremely fast Python package manager.
+Usage
+
+
+Commands
+
+uv authManage authentication
uv runRun a command or script
uv initCreate a new project
uv addAdd dependencies to the project
uv removeRemove dependencies from the project
uv versionRead or update the project's version
uv syncUpdate the project's environment
uv lockUpdate the project's lockfile
uv exportExport the project's lockfile to an alternate format
uv treeDisplay the project's dependency tree
uv formatFormat Python code in the project
uv toolRun and install commands provided by Python packages
uv pythonManage Python versions and installations
uv pipManage Python packages with a pip-compatible interface
uv venvCreate a virtual environment
uv buildBuild Python packages into source distributions and wheels
uv publishUpload distributions to an index
uv cacheManage uv's cache
uv selfManage the uv executable
uv helpDisplay documentation for a command
+
+uv auth
+Manage authentication
+Usage
+
+
+Commands
+
+uv auth loginLogin to a service
uv auth logoutLogout of a service
uv auth tokenShow the authentication token for a service
uv auth dirShow the path to the uv credentials directory
+
+uv auth login
+Login to a service
+Usage
+
+
+Arguments
+
+- SERVICE
The domain or URL of the service to log into
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--keyring-provider keyring-providerThe keyring provider to use for storage of credentials.
+Only --keyring-provider native is supported for login, which uses the system keyring via an integration built into uv.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--password passwordThe password to use for the service.
+Use - to read the password from stdin.
+--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--token, -t tokenThe token to use for the service.
+The username will be set to __token__.
+Use - to read the token from stdin.
+--username, -u usernameThe username to use for the service
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv auth logout
+Logout of a service
+Usage
+
+
+Arguments
+
+- SERVICE
The domain or URL of the service to logout from
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--keyring-provider keyring-providerThe keyring provider to use for storage of credentials.
+Only --keyring-provider native is supported for logout, which uses the system keyring via an integration built into uv.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--username, -u usernameThe username to logout
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv auth token
+Show the authentication token for a service
+Usage
+
+
+Arguments
+
+- SERVICE
The domain or URL of the service to lookup
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--keyring-provider keyring-providerThe keyring provider to use for reading credentials
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--username, -u usernameThe username to lookup
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv auth dir
+Show the path to the uv credentials directory.
+By default, credentials are stored in the uv data directory at $XDG_DATA_HOME/uv/credentials or $HOME/.local/share/uv/credentials on Unix and %APPDATA%\uv\data\credentials on Windows.
+The credentials directory may be overridden with $UV_CREDENTIALS_DIR.
+Credentials are only stored in this directory when the plaintext backend is used, as opposed to the native backend, which uses the system keyring.
+Usage
+
+
+Arguments
+
+- SERVICE
The domain or URL of the service to lookup
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv run
+Run a command or script.
+Ensures that the command runs in a Python environment.
+When used with a file ending in .py or an HTTP(S) URL, the file will be treated as a script and run with a Python interpreter, i.e., uv run file.py is equivalent to uv run python file.py. For URLs, the script is temporarily downloaded before execution. If the script contains inline dependency metadata, it will be installed into an isolated, ephemeral environment. When used with -, the input will be read from stdin, and treated as a Python script.
+When used in a project, the project environment will be created and updated before invoking the command.
+When used outside a project, if a virtual environment can be found in the current directory or a parent directory, the command will be run in that environment. Otherwise, the command will be run in the environment of the discovered interpreter.
+Arguments following the command (or script) are not interpreted as arguments to uv. All options to uv must be provided before the command, e.g., uv run --verbose foo. A -- can be used to separate the command from uv options for clarity, e.g., uv run --python 3.12 -- python.
+Usage
+
+
+Options
+
+--activePrefer the active virtual environment over the project's virtual environment.
+If the project virtual environment is active or no virtual environment is active, this has no effect.
+--all-extrasInclude all optional dependencies.
+Optional dependencies are defined via project.optional-dependencies in a pyproject.toml.
+This option is only available when running in a project.
+--all-groupsInclude dependencies from all dependency groups.
+--no-group can be used to exclude specific groups.
+--all-packagesRun the command with all workspace members installed.
+The workspace's environment (.venv) is updated to include all workspace members.
+Any extras or groups specified via --extra, --group, or related options will be applied to all workspace members.
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
+May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--env-file env-fileLoad environment variables from a .env file.
+Can be provided multiple times, with subsequent files overriding values defined in previous files.
+May also be set with the UV_ENV_FILE environment variable.
--exactPerform an exact sync, removing extraneous packages.
+When enabled, uv will remove any extraneous packages from the environment. By default, uv run will make the minimum necessary changes to satisfy the requirements.
+--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--extra extraInclude optional dependencies from the specified extra name.
+May be provided more than once.
+Optional dependencies are defined via project.optional-dependencies in a pyproject.toml.
+This option is only available when running in a project.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
+May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
+
+fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--frozenRun without updating the uv.lock file.
+Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the pyproject.toml includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.
+May also be set with the UV_FROZEN environment variable.
--group groupInclude dependencies from the specified dependency group.
+May be provided multiple times.
+--gui-scriptRun the given path as a Python GUI script.
+Using --gui-script will attempt to parse the path as a PEP 723 script and run it with pythonw.exe, irrespective of its extension. Only available on Windows.
+--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--isolatedRun the command in an isolated virtual environment.
+Usually, the project environment is reused for performance. This option forces a fresh environment to be used for the project, enforcing strict isolation between dependencies and declaration of requirements.
+An editable installation is still used for the project.
+When used with --with or --with-requirements, the additional dependencies will still be layered in a second environment.
+May also be set with the UV_ISOLATED environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--lockedAssert that the uv.lock will remain unchanged.
+Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
+May also be set with the UV_LOCKED environment variable.
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--module, -mRun a Python module.
+Equivalent to python -m <module>.
+--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
+May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
+May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
+May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518 are already installed.
+--no-build-package no-build-packageDon't build source distributions for a specific package
+May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-default-groupsIgnore the default dependency groups.
+uv includes the groups defined in tool.uv.default-groups by default. This disables that option, however, specific groups can still be included with --group.
+--no-devDisable the development dependency group.
+This option is an alias of --no-group dev. See --no-default-groups to disable all default groups instead.
+This option is only available when running in a project.
+May also be set with the UV_NO_DEV environment variable.
--no-editableInstall any editable dependencies, including the project and any workspace members, as non-editable
+May also be set with the UV_NO_EDITABLE environment variable.
--no-env-fileAvoid reading environment variables from a .env file
+May also be set with the UV_NO_ENV_FILE environment variable.
--no-extra no-extraExclude the specified optional dependencies, if --all-extras is supplied.
+May be provided multiple times.
+--no-group no-groupDisable the specified dependency group.
+This option always takes precedence over default groups, --all-groups, and --group.
+May be provided multiple times.
+May also be set with the UV_NO_GROUP environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-project, --no_workspaceAvoid discovering the project or workspace.
+Instead of searching for projects in the current directory and parent directories, run in an isolated, ephemeral environment populated by the --with requirements.
+If a virtual environment is active or found in a current or parent directory, it will be used as if there was no project or workspace.
+--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--no-syncAvoid syncing the virtual environment.
+Implies --frozen, as the project dependencies will be ignored (i.e., the lockfile will not be updated, since the environment will not be synced regardless).
+May also be set with the UV_NO_SYNC environment variable.
--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--only-devOnly include the development dependency group.
+The project and its dependencies will be omitted.
+This option is an alias for --only-group dev. Implies --no-default-groups.
+--only-group only-groupOnly include dependencies from the specified dependency group.
+The project and its dependencies will be omitted.
+May be provided multiple times. Implies --no-default-groups.
+--package packageRun the command in a specific package in the workspace.
+If the workspace member does not exist, uv will exit with an error.
+--prerelease prereleaseThe 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).
+May also be set with the UV_PRERELEASE environment variable.
Possible values:
+
+disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use for the run environment.
+If the interpreter request is satisfied by a discovered environment, the environment will be
+used.
+See uv python to view supported request formats.
+May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which requirements should be installed.
+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.
+When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
+WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.
+Possible values:
+
+windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--refreshRefresh all cached data
+--refresh-package refresh-packageRefresh cached data for a specific package
+--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
+--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
+--resolution resolutionThe 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).
+May also be set with the UV_RESOLUTION environment variable.
Possible values:
+
+highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script, -sRun the given path as a Python script.
+Using --script will attempt to parse the path as a PEP 723 script, irrespective of its extension.
+--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
+--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+--with, -w withRun with the given packages installed.
+When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.
+--with-editable with-editableRun with the given packages installed in editable mode.
+When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.
+--with-requirements with-requirementsRun with the packages listed in the given files.
+The following formats are supported: requirements.txt, .py files with inline metadata, and pylock.toml.
+The same environment semantics as --with apply.
+Using pyproject.toml, setup.py, or setup.cfg files is not allowed.
+
+
+uv init
+Create a new project.
+Follows the pyproject.toml specification.
+If a pyproject.toml already exists at the target, uv will exit with an error.
+If a pyproject.toml is found in any of the parent directories of the target path, the project will be added as a workspace member of the parent.
+Some project state is not created until needed, e.g., the project virtual environment (.venv) and lockfile (uv.lock) are lazily created during the first sync.
+Usage
+
+
+Arguments
+
+- PATH
The path to use for the project/script.
+Defaults to the current working directory when initializing an app or library; required when initializing a script. Accepts relative and absolute paths.
+If a pyproject.toml is found in any of the parent directories of the target path, the project will be added as a workspace member of the parent, unless --no-workspace is provided.
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--app, --applicationCreate a project for an application.
+This is the default behavior if --lib is not requested.
+This project kind is for web servers, scripts, and command-line interfaces.
+By default, an application is not intended to be built and distributed as a Python package. The --package option can be used to create an application that is distributable, e.g., if you want to distribute a command-line interface via PyPI.
+Fill in the authors field in the pyproject.toml.
+By default, uv will attempt to infer the author information from some sources (e.g., Git) (auto). Use --author-from git to only infer from Git configuration. Use --author-from none to avoid inferring the author information.
+Possible values:
+
+auto: Fetch the author information from some sources (e.g., Git) automaticallygit: Fetch the author information from Git configuration onlynone: Do not infer the author information
--bareOnly create a pyproject.toml.
+Disables creating extra files like README.md, the src/ tree, .python-version files, etc.
+--build-backend build-backendInitialize a build-backend of choice for the project.
+Implicitly sets --package.
+May also be set with the UV_INIT_BUILD_BACKEND environment variable.
Possible values:
+
+uv: Use uv as the project build backendhatch: Use hatchling as the project build backendflit: Use flit-core as the project build backendpdm: Use pdm-backend as the project build backendpoetry: Use poetry-core as the project build backendsetuptools: Use setuptools as the project build backendmaturin: Use maturin as the project build backendscikit: Use scikit-build-core as the project build backend
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--description descriptionSet the project description
+--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--lib, --libraryCreate a project for a library.
+A library is a project that is intended to be built and distributed as a Python package.
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--name nameThe name of the project.
+Defaults to the name of the directory.
+--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-descriptionDisable the description for the project
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-packageDo not set up the project to be built as a Python package.
+Does not include a [build-system] for the project.
+This is the default behavior when using --app.
+--no-pin-pythonDo not create a .python-version file for the project.
+By default, uv will create a .python-version file containing the minor version of the discovered Python interpreter, which will cause subsequent uv commands to use that version.
+--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-readmeDo not create a README.md file
+--no-workspace, --no-projectAvoid discovering a workspace and create a standalone project.
+By default, uv searches for workspaces in the current directory or any parent directory.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--packageSet up the project to be built as a Python package.
+Defines a [build-system] for the project.
+This is the default behavior when using --lib or --build-backend.
+When using --app, this will include a [project.scripts] entrypoint and use a src/ project structure.
+--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use to determine the minimum supported Python version.
+See uv python to view supported request formats.
+May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--scriptCreate a script.
+A script is a standalone file with embedded metadata enumerating its dependencies, along with any Python version requirements, as defined in the PEP 723 specification.
+PEP 723 scripts can be executed directly with uv run.
+By default, adds a requirement on the system Python version; use --python to specify an alternative Python version requirement.
+--vcs vcsInitialize a version control system for the project.
+By default, uv will initialize a Git repository (git). Use --vcs none to explicitly avoid initializing a version control system.
+Possible values:
+
+git: Use Git for version controlnone: Do not use any version control system
--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv add
+Add dependencies to the project.
+Dependencies are added to the project's pyproject.toml file.
+If a given dependency exists already, it will be updated to the new version specifier unless it includes markers that differ from the existing specifier in which case another entry for the dependency will be added.
+The lockfile and project environment will be updated to reflect the added dependencies. To skip updating the lockfile, use --frozen. To skip updating the environment, use --no-sync.
+If any of the requested dependencies cannot be found, uv will exit with an error, unless the --frozen flag is provided, in which case uv will add the dependencies verbatim without checking that they exist or are compatible with the project.
+uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.
+Usage
+
+
+Arguments
+
+- PACKAGES
The packages to add, as PEP 508 requirements (e.g., ruff==0.5.0)
+
+
+Options
+
+--activePrefer the active virtual environment over the project's virtual environment.
+If the project virtual environment is active or no virtual environment is active, this has no effect.
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--bounds boundsThe kind of version specifier to use when adding dependencies.
+When adding a dependency to the project, if no constraint or URL is provided, a constraint is added based on the latest compatible version of the package. By default, a lower bound constraint is used, e.g., >=1.2.3.
+When --frozen is provided, no resolution is performed, and dependencies are always added without constraints.
+This option is in preview and may change in any future release.
+Possible values:
+
+lower: Only a lower bound, e.g., >=1.2.3major: Allow the same major version, similar to the semver caret, e.g., >=1.2.3, <2.0.0minor: Allow the same minor version, similar to the semver tilde, e.g., >=1.2.3, <1.3.0exact: Pin the exact version, e.g., ==1.2.3
--branch branchBranch to use when adding a dependency from Git
+--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
+May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--constraints, --constraint, -c constraintsConstrain versions using the given requirements files.
+Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. The constraints will not be added to the project's pyproject.toml file, but will be respected during dependency resolution.
+This is equivalent to pip's --constraint option.
+May also be set with the UV_CONSTRAINT environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--devAdd the requirements to the development dependency group.
+This option is an alias for --group dev.
+May also be set with the UV_DEV environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--editableAdd the requirements as editable
+--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--extra extraExtras to enable for the dependency.
+May be provided more than once.
+To add this dependency to an optional extra instead, see --optional.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
+May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
+
+fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--frozenAdd dependencies without re-locking the project.
+The project environment will not be synced.
+May also be set with the UV_FROZEN environment variable.
--group groupAdd the requirements to the specified dependency group.
+These requirements will not be included in the published metadata for the project.
+--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--lockedAssert that the uv.lock will remain unchanged.
+Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
+May also be set with the UV_LOCKED environment variable.
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--marker, -m markerApply this marker to all added packages
+--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
+May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
+May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
+May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518 are already installed.
+--no-build-package no-build-packageDon't build source distributions for a specific package
+May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-install-localDo not install local path dependencies
+Skips the current project, workspace members, and any other local (path or editable) packages. Only remote/indexed dependencies are installed. Useful in Docker builds to cache heavy third-party dependencies first and layer local packages separately.
+--no-install-projectDo not install the current project.
+By default, the current project is installed into the environment with all of its dependencies. The --no-install-project option allows the project to be excluded, but all of its dependencies are still installed. This is particularly useful in situations like building Docker images where installing the project separately from its dependencies allows optimal layer caching.
+--no-install-workspaceDo not install any workspace members, including the current project.
+By default, all of the workspace members and their dependencies are installed into the environment. The --no-install-workspace option allows exclusion of all the workspace members while retaining their dependencies. This is particularly useful in situations like building Docker images where installing the workspace separately from its dependencies allows optimal layer caching.
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--no-syncAvoid syncing the virtual environment
+May also be set with the UV_NO_SYNC environment variable.
--no-workspaceDon't add the dependency as a workspace member.
+By default, when adding a dependency that's a local path and is within the workspace directory, uv will add it as a workspace member; pass --no-workspace to add the package as direct path dependency instead.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--optional optionalAdd the requirements to the package's optional dependencies for the specified extra.
+The group may then be activated when installing the project with the --extra flag.
+To enable an optional extra for this requirement instead, see --extra.
+--package packageAdd the dependency to a specific package in the workspace
+--prerelease prereleaseThe 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).
+May also be set with the UV_PRERELEASE environment variable.
Possible values:
+
+disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use for resolving and syncing.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--raw, --raw-sourcesAdd a dependency as provided.
+By default, uv will use the tool.uv.sources section to record source information for Git, local, editable, and direct URL requirements. When --raw is provided, uv will add source requirements to project.dependencies, rather than tool.uv.sources.
+Additionally, by default, uv will add bounds to your dependency, e.g., foo>=1.0.0. When --raw is provided, uv will add the dependency without bounds.
+--refreshRefresh all cached data
+--refresh-package refresh-packageRefresh cached data for a specific package
+--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
+--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
+--requirements, --requirement, -r requirementsAdd the packages listed in the given files.
+The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.
+--resolution resolutionThe 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).
+May also be set with the UV_RESOLUTION environment variable.
Possible values:
+
+highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--rev revCommit to use when adding a dependency from Git
+--script scriptAdd the dependency to the specified Python script, rather than to a project.
+If provided, uv will add the dependency to the script's inline metadata table, in adherence with PEP 723. If no such inline metadata table is present, a new one will be created and added to the script. When executed via uv run, uv will create a temporary environment for the script with all inline dependencies installed.
+--tag tagTag to use when adding a dependency from Git
+--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
+--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+--workspaceAdd the dependency as a workspace member.
+By default, uv will add path dependencies that are within the workspace directory as workspace members. When used with a path dependency, the package will be added to the workspace's members list in the root pyproject.toml file.
+
+
+uv remove
+Remove dependencies from the project.
+Dependencies are removed from the project's pyproject.toml file.
+If multiple entries exist for a given dependency, i.e., each with different markers, all of the entries will be removed.
+The lockfile and project environment will be updated to reflect the removed dependencies. To skip updating the lockfile, use --frozen. To skip updating the environment, use --no-sync.
+If any of the requested dependencies are not present in the project, uv will exit with an error.
+If a package has been manually installed in the environment, i.e., with uv pip install, it will not be removed by uv remove.
+uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.
+Usage
+
+
+Arguments
+
+- PACKAGES
The names of the dependencies to remove (e.g., ruff)
+
+
+Options
+
+--activePrefer the active virtual environment over the project's virtual environment.
+If the project virtual environment is active or no virtual environment is active, this has no effect.
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
+May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--devRemove the packages from the development dependency group.
+This option is an alias for --group dev.
+May also be set with the UV_DEV environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
+May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
+
+fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--frozenRemove dependencies without re-locking the project.
+The project environment will not be synced.
+May also be set with the UV_FROZEN environment variable.
--group groupRemove the packages from the specified dependency group
+--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--lockedAssert that the uv.lock will remain unchanged.
+Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
+May also be set with the UV_LOCKED environment variable.
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
+May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
+May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
+May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518 are already installed.
+--no-build-package no-build-packageDon't build source distributions for a specific package
+May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--no-syncAvoid syncing the virtual environment after re-locking the project
+May also be set with the UV_NO_SYNC environment variable.
--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--optional optionalRemove the packages from the project's optional dependencies for the specified extra
+--package packageRemove the dependencies from a specific package in the workspace
+--prerelease prereleaseThe 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).
+May also be set with the UV_PRERELEASE environment variable.
Possible values:
+
+disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use for resolving and syncing.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--refreshRefresh all cached data
+--refresh-package refresh-packageRefresh cached data for a specific package
+--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
+--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
+--resolution resolutionThe 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).
+May also be set with the UV_RESOLUTION environment variable.
Possible values:
+
+highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script scriptRemove the dependency from the specified Python script, rather than from a project.
+If provided, uv will remove the dependency from the script's inline metadata table, in adherence with PEP 723.
+--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
+--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv version
+Read or update the project's version
+Usage
+
+
+Arguments
+
+- VALUE
Set the project version to this value
+To update the project using semantic versioning components instead, use --bump.
+
+
+Options
+
+--activePrefer the active virtual environment over the project's virtual environment.
+If the project virtual environment is active or no virtual environment is active, this has no effect.
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--bump bumpUpdate the project version using the given semantics
+This flag can be passed multiple times.
+Possible values:
+
+major: Increase the major version (e.g., 1.2.3 => 2.0.0)minor: Increase the minor version (e.g., 1.2.3 => 1.3.0)patch: Increase the patch version (e.g., 1.2.3 => 1.2.4)stable: Move from a pre-release to stable version (e.g., 1.2.3b4.post5.dev6 => 1.2.3)alpha: Increase the alpha version (e.g., 1.2.3a4 => 1.2.3a5)beta: Increase the beta version (e.g., 1.2.3b4 => 1.2.3b5)rc: Increase the rc version (e.g., 1.2.3rc4 => 1.2.3rc5)post: Increase the post version (e.g., 1.2.3.post5 => 1.2.3.post6)dev: Increase the dev version (e.g., 1.2.3a4.dev6 => 1.2.3.dev7)
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
+May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runDon't write a new version to the pyproject.toml
+Instead, the version will be displayed.
+--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
+May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
+
+fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--frozenUpdate the version without re-locking the project.
+The project environment will not be synced.
+May also be set with the UV_FROZEN environment variable.
--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--lockedAssert that the uv.lock will remain unchanged.
+Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
+May also be set with the UV_LOCKED environment variable.
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
+May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
+May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
+May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518 are already installed.
+--no-build-package no-build-packageDon't build source distributions for a specific package
+May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--no-syncAvoid syncing the virtual environment after re-locking the project
+May also be set with the UV_NO_SYNC environment variable.
--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--output-format output-formatThe format of the output
+[default: text]
Possible values:
+
+text: Display the version as plain textjson: Display the version as JSON
--package packageUpdate the version of a specific package in the workspace
+--prerelease prereleaseThe 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).
+May also be set with the UV_PRERELEASE environment variable.
Possible values:
+
+disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use for resolving and syncing.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--refreshRefresh all cached data
+--refresh-package refresh-packageRefresh cached data for a specific package
+--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
+--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
+--resolution resolutionThe 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).
+May also be set with the UV_RESOLUTION environment variable.
Possible values:
+
+highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--shortOnly show the version
+By default, uv will show the project name before the version.
+--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
+--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv sync
+Update the project's environment.
+Syncing ensures that all project dependencies are installed and up-to-date with the lockfile.
+By default, an exact sync is performed: uv removes packages that are not declared as dependencies of the project. Use the --inexact flag to keep extraneous packages. Note that if an extraneous package conflicts with a project dependency, it will still be removed. Additionally, if --no-build-isolation is used, uv will not remove extraneous packages to avoid removing possible build dependencies.
+If the project virtual environment (.venv) does not exist, it will be created.
+The project is re-locked before syncing unless the --locked or --frozen flag is provided.
+uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.
+Note that, when installing from a lockfile, uv will not provide warnings for yanked package versions.
+Usage
+
+
+Options
+
+--activeSync dependencies to the active virtual environment.
+Instead of creating or updating the virtual environment for the project or script, the active virtual environment will be preferred, if the VIRTUAL_ENV environment variable is set.
+--all-extrasInclude all optional dependencies.
+When two or more extras are declared as conflicting in tool.uv.conflicts, using this flag will always result in an error.
+Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.
+--all-groupsInclude dependencies from all dependency groups.
+--no-group can be used to exclude specific groups.
+--all-packagesSync all packages in the workspace.
+The workspace's environment (.venv) is updated to include all workspace members.
+Any extras or groups specified via --extra, --group, or related options will be applied to all workspace members.
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--checkCheck if the Python environment is synchronized with the project.
+If the environment is not up to date, uv will exit with an error.
+--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
+May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runPerform a dry run, without writing the lockfile or modifying the project environment.
+In dry-run mode, uv will resolve the project's dependencies and report on the resulting changes to both the lockfile and the project environment, but will not modify either.
+--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--extra extraInclude optional dependencies from the specified extra name.
+May be provided more than once.
+When multiple extras or groups are specified that appear in tool.uv.conflicts, uv will report an error.
+Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
+May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
+
+fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--frozenSync without updating the uv.lock file.
+Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the pyproject.toml includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.
+May also be set with the UV_FROZEN environment variable.
--group groupInclude dependencies from the specified dependency group.
+When multiple extras or groups are specified that appear in tool.uv.conflicts, uv will report an error.
+May be provided multiple times.
+--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--inexact, --no-exactDo not remove extraneous packages present in the environment.
+When enabled, uv will make the minimum necessary changes to satisfy the requirements. By default, syncing will remove any extraneous packages from the environment
+--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--lockedAssert that the uv.lock will remain unchanged.
+Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
+May also be set with the UV_LOCKED environment variable.
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
+May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
+May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
+May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518 are already installed.
+--no-build-package no-build-packageDon't build source distributions for a specific package
+May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-default-groupsIgnore the default dependency groups.
+uv includes the groups defined in tool.uv.default-groups by default. This disables that option, however, specific groups can still be included with --group.
+--no-devDisable the development dependency group.
+This option is an alias of --no-group dev. See --no-default-groups to disable all default groups instead.
+May also be set with the UV_NO_DEV environment variable.
--no-editableInstall any editable dependencies, including the project and any workspace members, as non-editable
+May also be set with the UV_NO_EDITABLE environment variable.
--no-extra no-extraExclude the specified optional dependencies, if --all-extras is supplied.
+May be provided multiple times.
+--no-group no-groupDisable the specified dependency group.
+This option always takes precedence over default groups, --all-groups, and --group.
+May be provided multiple times.
+May also be set with the UV_NO_GROUP environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-install-localDo not install local path dependencies
+Skips the current project, workspace members, and any other local (path or editable) packages. Only remote/indexed dependencies are installed. Useful in Docker builds to cache heavy third-party dependencies first and layer local packages separately.
+--no-install-package no-install-packageDo not install the given package(s).
+By default, all of the project's dependencies are installed into the environment. The --no-install-package option allows exclusion of specific packages. Note this can result in a broken environment, and should be used with caution.
+--no-install-projectDo not install the current project.
+By default, the current project is installed into the environment with all of its dependencies. The --no-install-project option allows the project to be excluded, but all of its dependencies are still installed. This is particularly useful in situations like building Docker images where installing the project separately from its dependencies allows optimal layer caching.
+--no-install-workspaceDo not install any workspace members, including the root project.
+By default, all of the workspace members and their dependencies are installed into the environment. The --no-install-workspace option allows exclusion of all the workspace members while retaining their dependencies. This is particularly useful in situations like building Docker images where installing the workspace separately from its dependencies allows optimal layer caching.
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--only-devOnly include the development dependency group.
+The project and its dependencies will be omitted.
+This option is an alias for --only-group dev. Implies --no-default-groups.
+--only-group only-groupOnly include dependencies from the specified dependency group.
+The project and its dependencies will be omitted.
+May be provided multiple times. Implies --no-default-groups.
+--output-format output-formatSelect the output format
+[default: text]
Possible values:
+
+text: Display the result in a human-readable formatjson: Display the result in JSON format
--package packageSync for specific packages in the workspace.
+The workspace's environment (.venv) is updated to reflect the subset of dependencies declared by the specified workspace member packages.
+If any workspace member does not exist, uv will exit with an error.
+--prerelease prereleaseThe 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).
+May also be set with the UV_PRERELEASE environment variable.
Possible values:
+
+disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use for the project environment.
+By default, the first interpreter that meets the project's requires-python constraint is
+used.
+If a Python interpreter in a virtual environment is provided, the packages will not be
+synced to the given environment. The interpreter will be used to create a virtual
+environment in the project.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which requirements should be installed.
+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.
+When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
+WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.
+Possible values:
+
+windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--refreshRefresh all cached data
+--refresh-package refresh-packageRefresh cached data for a specific package
+--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
+--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
+--resolution resolutionThe 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).
+May also be set with the UV_RESOLUTION environment variable.
Possible values:
+
+highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script scriptSync the environment for a Python script, rather than the current project.
+If provided, uv will sync the dependencies based on the script's inline metadata table, in adherence with PEP 723.
+--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
+--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv lock
+Update the project's lockfile.
+If the project lockfile (uv.lock) does not exist, it will be created. If a lockfile is present, its contents will be used as preferences for the resolution.
+If there are no changes to the project's dependencies, locking will have no effect unless the --upgrade flag is provided.
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--checkCheck if the lockfile is up-to-date.
+Asserts that the uv.lock would remain unchanged after a resolution. If the lockfile is missing or needs to be updated, uv will exit with an error.
+Equivalent to --locked.
+--check-exists, --frozenAssert that a uv.lock exists without checking if it is up-to-date.
+Equivalent to --frozen.
+May also be set with the UV_FROZEN environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runPerform a dry run, without writing the lockfile.
+In dry-run mode, uv will resolve the project's dependencies and report on the resulting changes, but will not write the lockfile to disk.
+--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for a specific package to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
+May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
+
+fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+This option is only used when building source distributions.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
+May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
+May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
+May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518 are already installed.
+--no-build-package no-build-packageDon't build source distributions for a specific package
+May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--prerelease prereleaseThe 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).
+May also be set with the UV_PRERELEASE environment variable.
Possible values:
+
+disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use during resolution.
+A Python interpreter is required for building source distributions to determine package
+metadata when there are not wheels.
+The interpreter is also used as the fallback value for the minimum Python version if
+requires-python is not set.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--refreshRefresh all cached data
+--refresh-package refresh-packageRefresh cached data for a specific package
+--resolution resolutionThe 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).
+May also be set with the UV_RESOLUTION environment variable.
Possible values:
+
+highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script scriptLock the specified Python script, rather than the current project.
+If provided, uv will lock the script (based on its inline metadata table, in adherence with PEP 723) to a .lock file adjacent to the script itself.
+--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
+--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv export
+Export the project's lockfile to an alternate format.
+At present, both requirements.txt and pylock.toml (PEP 751) formats are supported.
+The project is re-locked before exporting unless the --locked or --frozen flag is provided.
+uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.
+If operating in a workspace, the root will be exported by default; however, specific members can be selected using the --package option.
+Usage
+
+
+Options
+
+--all-extrasInclude all optional dependencies
+--all-groupsInclude dependencies from all dependency groups.
+--no-group can be used to exclude specific groups.
+--all-packagesExport the entire workspace.
+The dependencies for all workspace members will be included in the exported requirements file.
+Any extras or groups specified via --extra, --group, or related options will be applied to all workspace members.
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for a specific package to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--extra extraInclude optional dependencies from the specified extra name.
+May be provided more than once.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
+May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
+
+fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--format formatThe format to which uv.lock should be exported.
+Supports both requirements.txt and pylock.toml (PEP 751) output formats.
+uv will infer the output format from the file extension of the output file, if provided. Otherwise, defaults to requirements.txt.
+Possible values:
+
+requirements.txt: Export in requirements.txt formatpylock.toml: Export in pylock.toml format
--frozenDo not update the uv.lock before exporting.
+If a uv.lock does not exist, uv will exit with an error.
+May also be set with the UV_FROZEN environment variable.
--group groupInclude dependencies from the specified dependency group.
+May be provided multiple times.
+--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+This option is only used when building source distributions.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--lockedAssert that the uv.lock will remain unchanged.
+Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
+May also be set with the UV_LOCKED environment variable.
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-annotateExclude comment annotations indicating the source of each package
+--no-binaryDon'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.
+May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
+May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
+May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518 are already installed.
+--no-build-package no-build-packageDon't build source distributions for a specific package
+May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-default-groupsIgnore the default dependency groups.
+uv includes the groups defined in tool.uv.default-groups by default. This disables that option, however, specific groups can still be included with --group.
+--no-devDisable the development dependency group.
+This option is an alias of --no-group dev. See --no-default-groups to disable all default groups instead.
+May also be set with the UV_NO_DEV environment variable.
--no-editableExport any editable dependencies, including the project and any workspace members, as non-editable
+May also be set with the UV_NO_EDITABLE environment variable.
--no-emit-local, --no-install-localDo not include local path dependencies in the exported requirements.
+Omits the current project, workspace members, and any other local (path or editable) packages from the export. Only remote/indexed dependencies are written. Useful for Docker and CI flows that want to export and cache third-party dependencies first.
+--no-emit-package, --no-install-package no-emit-packageDo not emit the given package(s).
+By default, all of the project's dependencies are included in the exported requirements file. The --no-emit-package option allows exclusion of specific packages.
+--no-emit-project, --no-install-projectDo not emit the current project.
+By default, the current project is included in the exported requirements file with all of its dependencies. The --no-emit-project option allows the project to be excluded, but all of its dependencies to remain included.
+--no-emit-workspace, --no-install-workspaceDo not emit any workspace members, including the root project.
+By default, all workspace members and their dependencies are included in the exported requirements file, with all of their dependencies. The --no-emit-workspace option allows exclusion of all the workspace members while retaining their dependencies.
+--no-extra no-extraExclude the specified optional dependencies, if --all-extras is supplied.
+May be provided multiple times.
+--no-group no-groupDisable the specified dependency group.
+This option always takes precedence over default groups, --all-groups, and --group.
+May be provided multiple times.
+May also be set with the UV_NO_GROUP environment variable.
--no-hashesOmit hashes in the generated output
+--no-headerExclude the comment header at the top of the generated output file
+--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--only-devOnly include the development dependency group.
+The project and its dependencies will be omitted.
+This option is an alias for --only-group dev. Implies --no-default-groups.
+--only-group only-groupOnly include dependencies from the specified dependency group.
+The project and its dependencies will be omitted.
+May be provided multiple times. Implies --no-default-groups.
+--output-file, -o output-fileWrite the exported requirements to the given file
+--package packageExport the dependencies for specific packages in the workspace.
+If any workspace member does not exist, uv will exit with an error.
+--prerelease prereleaseThe 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).
+May also be set with the UV_PRERELEASE environment variable.
Possible values:
+
+disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--prune packagePrune the given package from the dependency tree.
+Pruned packages will be excluded from the exported requirements file, as will any dependencies that are no longer required after the pruned package is removed.
+--python, -p pythonThe Python interpreter to use during resolution.
+A Python interpreter is required for building source distributions to determine package
+metadata when there are not wheels.
+The interpreter is also used as the fallback value for the minimum Python version if
+requires-python is not set.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--refreshRefresh all cached data
+--refresh-package refresh-packageRefresh cached data for a specific package
+--resolution resolutionThe 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).
+May also be set with the UV_RESOLUTION environment variable.
Possible values:
+
+highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script scriptExport the dependencies for the specified PEP 723 Python script, rather than the current project.
+If provided, uv will resolve the dependencies based on its inline metadata table, in adherence with PEP 723.
+--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
+--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv tree
+Display the project's dependency tree
+Usage
+
+
+Options
+
+--all-groupsInclude dependencies from all dependency groups.
+--no-group can be used to exclude specific groups.
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--depth, -d depthMaximum display depth of the dependency tree
+[default: 255]
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for a specific package to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
+May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
+
+fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--frozenDisplay the requirements without locking the project.
+If the lockfile is missing, uv will exit with an error.
+May also be set with the UV_FROZEN environment variable.
--group groupInclude dependencies from the specified dependency group.
+May be provided multiple times.
+--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--invert, --reverseShow the reverse dependencies for the given package. This flag will invert the tree and display the packages that depend on the given package
+--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+This option is only used when building source distributions.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--lockedAssert that the uv.lock will remain unchanged.
+Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
+May also be set with the UV_LOCKED environment variable.
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
+May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
+May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
+May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518 are already installed.
+--no-build-package no-build-packageDon't build source distributions for a specific package
+May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-dedupeDo not de-duplicate repeated dependencies. Usually, when a package has already displayed its dependencies, further occurrences will not re-display its dependencies, and will include a (*) to indicate it has already been shown. This flag will cause those duplicates to be repeated
+--no-default-groupsIgnore the default dependency groups.
+uv includes the groups defined in tool.uv.default-groups by default. This disables that option, however, specific groups can still be included with --group.
+--no-devDisable the development dependency group.
+This option is an alias of --no-group dev. See --no-default-groups to disable all default groups instead.
+May also be set with the UV_NO_DEV environment variable.
--no-group no-groupDisable the specified dependency group.
+This option always takes precedence over default groups, --all-groups, and --group.
+May be provided multiple times.
+May also be set with the UV_NO_GROUP environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--only-devOnly include the development dependency group.
+The project and its dependencies will be omitted.
+This option is an alias for --only-group dev. Implies --no-default-groups.
+--only-group only-groupOnly include dependencies from the specified dependency group.
+The project and its dependencies will be omitted.
+May be provided multiple times. Implies --no-default-groups.
+--outdatedShow the latest available version of each package in the tree
+--package packageDisplay only the specified packages
+--prerelease prereleaseThe 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).
+May also be set with the UV_PRERELEASE environment variable.
Possible values:
+
+disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--prune prunePrune the given package from the display of the dependency tree
+--python, -p pythonThe Python interpreter to use for locking and filtering.
+By default, the tree is filtered to match the platform as reported by the Python
+interpreter. Use --universal to display the tree for all platforms, or use
+--python-version or --python-platform to override a subset of markers.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform to use when filtering the tree.
+For example, pass --platform windows to display the dependencies that would be included when installing on Windows.
+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.
+Possible values:
+
+windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--python-version python-versionThe Python version to use when filtering the tree.
+For example, pass --python-version 3.10 to display the dependencies that would be included when installing on Python 3.10.
+Defaults to the version of the discovered Python interpreter.
+--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--resolution resolutionThe 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).
+May also be set with the UV_RESOLUTION environment variable.
Possible values:
+
+highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script scriptShow the dependency tree the specified PEP 723 Python script, rather than the current project.
+If provided, uv will resolve the dependencies based on its inline metadata table, in adherence with PEP 723.
+--show-sizesShow compressed wheel sizes for packages in the tree
+--universalShow a platform-independent dependency tree.
+Shows resolved package versions for all Python versions and platforms, rather than filtering to those that are relevant for the current environment.
+Multiple versions may be shown for a each package.
+--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
+--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv format
+Format Python code in the project.
+Formats Python code using the Ruff formatter. By default, all Python files in the project are formatted. This command has the same behavior as running ruff format in the project root.
+To check if files are formatted without modifying them, use --check. To see a diff of formatting changes, use --diff.
+Additional arguments can be passed to Ruff after --.
+Usage
+
+
+Arguments
+
+- EXTRA_ARGS
Additional arguments to pass to Ruff.
+For example, use uv format -- --line-length 100 to set the line length or uv format -- src/module/foo.py to format a specific file.
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--checkCheck if files are formatted without applying changes
+--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--diffShow a diff of formatting changes without applying them.
+Implies --check.
+--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-projectAvoid discovering a project or workspace.
+Instead of running the formatter in the context of the current project, run it in the context of the current directory. This is useful when the current directory is not a project.
+--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+--version versionThe version of Ruff to use for formatting.
+By default, a version of Ruff pinned by uv will be used.
+
+
+uv tool
+Run and install commands provided by Python packages
+Usage
+
+
+Commands
+
+uv tool runRun a command provided by a Python package
uv tool installInstall commands provided by a Python package
uv tool upgradeUpgrade installed tools
uv tool listList installed tools
uv tool uninstallUninstall a tool
uv tool update-shellEnsure that the tool executable directory is on the PATH
uv tool dirShow the path to the uv tools directory
+
+uv tool run
+Run a command provided by a Python package.
+By default, the package to install is assumed to match the command name.
+The name of the command can include an exact version in the format <package>@<version>, e.g., uv tool run ruff@0.3.0. If more complex version specification is desired or if the command is provided by a different package, use --from.
+uvx can be used to invoke Python, e.g., with uvx python or uvx python@<version>. A Python interpreter will be started in an isolated virtual environment.
+If the tool was previously installed, i.e., via uv tool install, the installed version will be used unless a version is requested or the --isolated flag is used.
+uvx is provided as a convenient alias for uv tool run, their behavior is identical.
+If no command is provided, the installed tools are displayed.
+Packages are installed into an ephemeral virtual environment in the uv cache directory.
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--build-constraints, --build-constraint, -b build-constraintsConstrain build dependencies using the given requirements files when building source distributions.
+Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
+May also be set with the UV_BUILD_CONSTRAINT environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
+May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--constraints, --constraint, -c constraintsConstrain versions using the given requirements files.
+Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
+This is equivalent to pip's --constraint option.
+May also be set with the UV_CONSTRAINT environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--env-file env-fileLoad environment variables from a .env file.
+Can be provided multiple times, with subsequent files overriding values defined in previous files.
+May also be set with the UV_ENV_FILE environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
+May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
+
+fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--from fromUse the given package to provide the command.
+By default, the package name is assumed to match the command name.
+--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--isolatedRun the tool in an isolated virtual environment, ignoring any already-installed tools
+May also be set with the UV_ISOLATED environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
+May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
+May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
+May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518 are already installed.
+--no-build-package no-build-packageDon't build source distributions for a specific package
+May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-env-fileAvoid reading environment variables from a .env file
+May also be set with the UV_NO_ENV_FILE environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--overrides, --override overridesOverride versions using the given requirements files.
+Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.
+While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.
+May also be set with the UV_OVERRIDE environment variable.
--prerelease prereleaseThe 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).
+May also be set with the UV_PRERELEASE environment variable.
Possible values:
+
+disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use to build the run environment.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which requirements should be installed.
+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.
+When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
+WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.
+Possible values:
+
+windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--refreshRefresh all cached data
+--refresh-package refresh-packageRefresh cached data for a specific package
+--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
+--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
+--resolution resolutionThe 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).
+May also be set with the UV_RESOLUTION environment variable.
Possible values:
+
+highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
+--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+--with, -w withRun with the given packages installed
+--with-editable with-editableRun with the given packages installed in editable mode
+When used in a project, these dependencies will be layered on top of the uv tool's environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified.
+--with-requirements with-requirementsRun with the packages listed in the given files.
+The following formats are supported: requirements.txt, .py files with inline metadata, and pylock.toml.
+
+
+uv tool install
+Install commands provided by a Python package.
+Packages are installed into an isolated virtual environment in the uv tools directory. The executables are linked the tool executable directory, which is determined according to the XDG standard and can be retrieved with uv tool dir --bin.
+If the tool was previously installed, the existing tool will generally be replaced.
+Usage
+
+
+Arguments
+
+- PACKAGE
The package to install commands from
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--build-constraints, --build-constraint, -b build-constraintsConstrain build dependencies using the given requirements files when building source distributions.
+Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
+May also be set with the UV_BUILD_CONSTRAINT environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
+May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--constraints, --constraint, -c constraintsConstrain versions using the given requirements files.
+Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
+This is equivalent to pip's --constraint option.
+May also be set with the UV_CONSTRAINT environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--editable, -eInstall the target package in editable mode, such that changes in the package's source directory are reflected without reinstallation
+--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--excludes, --exclude excludesExclude packages from resolution using the given requirements files.
+Excludes files are requirements.txt-like files that specify packages to exclude from the resolution. When a package is excluded, it will be omitted from the dependency list entirely and its own dependencies will be ignored during the resolution phase. Excludes are unconditional in that requirement specifiers and markers are ignored; any package listed in the provided file will be omitted from all resolved environments.
+May also be set with the UV_EXCLUDE environment variable.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--forceForce installation of the tool.
+Will replace any existing entry points with the same name in the executable directory.
+--fork-strategy fork-strategyThe 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.
+May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
+
+fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
+May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
+May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
+May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518 are already installed.
+--no-build-package no-build-packageDon't build source distributions for a specific package
+May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--overrides, --override overridesOverride versions using the given requirements files.
+Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.
+While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.
+May also be set with the UV_OVERRIDE environment variable.
--prerelease prereleaseThe 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).
+May also be set with the UV_PRERELEASE environment variable.
Possible values:
+
+disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use to build the tool environment.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which requirements should be installed.
+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.
+When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
+WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.
+Possible values:
+
+windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--refreshRefresh all cached data
+--refresh-package refresh-packageRefresh cached data for a specific package
+--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
+--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
+--resolution resolutionThe 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).
+May also be set with the UV_RESOLUTION environment variable.
Possible values:
+
+highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
+--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+--with, -w withInclude the following additional requirements
+--with-editable with-editableInclude the given packages in editable mode
+--with-executables-from with-executables-fromInstall executables from the following packages
+--with-requirements with-requirementsRun with the packages listed in the given files.
+The following formats are supported: requirements.txt, .py files with inline metadata, and pylock.toml.
+
+
+uv tool upgrade
+Upgrade installed tools.
+If a tool was installed with version constraints, they will be respected on upgrade — to upgrade a tool beyond the originally provided constraints, use uv tool install again.
+If a tool was installed with specific settings, they will be respected on upgraded. For example, if --prereleases allow was provided during installation, it will continue to be respected in upgrades.
+Usage
+
+
+Arguments
+
+- NAME
The name of the tool to upgrade, along with an optional version specifier
+
+
+Options
+
+--allUpgrade all tools
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
+May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-setting-package, --config-settings-package config-setting-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
+May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
+
+fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
+May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
+May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
+May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518 are already installed.
+--no-build-package no-build-packageDon't build source distributions for a specific package
+May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--prerelease prereleaseThe 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).
+May also be set with the UV_PRERELEASE environment variable.
Possible values:
+
+disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonUpgrade a tool, and specify it to use the given Python interpreter to build its environment.
+Use with --all to apply to all tools.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which requirements should be installed.
+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.
+When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
+WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.
+Possible values:
+
+windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
+--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
+--resolution resolutionThe 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).
+May also be set with the UV_RESOLUTION environment variable.
Possible values:
+
+highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv tool list
+List installed tools
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--show-extrasWhether to display the extra requirements installed with each tool
+--show-pathsWhether to display the path to each tool environment and installed executable
+--show-pythonWhether to display the Python version associated with each tool
+--show-version-specifiersWhether to display the version specifier(s) used to install each tool
+--show-withWhether to display the additional requirements installed with each tool
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv tool uninstall
+Uninstall a tool
+Usage
+
+
+Arguments
+
+- NAME
The name of the tool to uninstall
+
+
+Options
+
+--allUninstall all tools
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv tool update-shell
+Ensure that the tool executable directory is on the PATH.
+If the tool executable directory is not present on the PATH, uv will attempt to add it to the relevant shell configuration files.
+If the shell configuration files already include a blurb to add the executable directory to the path, but the directory is not present on the PATH, uv will exit with an error.
+The tool executable directory is determined according to the XDG standard and can be retrieved with uv tool dir --bin.
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv tool dir
+Show the path to the uv tools directory.
+The tools directory is used to store environments and metadata for installed tools.
+By default, tools are stored in the uv data directory at $XDG_DATA_HOME/uv/tools or $HOME/.local/share/uv/tools on Unix and %APPDATA%\uv\data\tools on Windows.
+The tool installation directory may be overridden with $UV_TOOL_DIR.
+To instead view the directory uv installs executables into, use the --bin flag.
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--binShow the directory into which uv tool will install executables.
+By default, uv tool dir shows the directory into which the tool Python environments
+themselves are installed, rather than the directory containing the linked executables.
+The tool executable directory is determined according to the XDG standard and is derived
+from the following environment variables, in order of preference:
+
+$UV_TOOL_BIN_DIR$XDG_BIN_HOME$XDG_DATA_HOME/../bin$HOME/.local/bin
+--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv python
+Manage Python versions and installations
+Generally, uv first searches for Python in a virtual environment, either active or in a
+.venv directory in the current working directory or any parent directory. If a virtual
+environment is not required, uv will then search for a Python interpreter. Python
+interpreters are found by searching for Python executables in the PATH environment
+variable.
+On Windows, the registry is also searched for Python executables.
+By default, uv will download Python if a version cannot be found. This behavior can be
+disabled with the --no-python-downloads flag or the python-downloads setting.
+The --python option allows requesting a different interpreter.
+The following Python version request formats are supported:
+
+<version> e.g. 3, 3.12, 3.12.3<version-specifier> e.g. >=3.12,<3.13<version><short-variant> (e.g., 3.13t, 3.12.0d)<version>+<variant> (e.g., 3.13+freethreaded, 3.12.0+debug)<implementation> e.g. cpython or cp<implementation>@<version> e.g. cpython@3.12<implementation><version> e.g. cpython3.12 or cp312<implementation><version-specifier> e.g. cpython>=3.12,<3.13<implementation>-<version>-<os>-<arch>-<libc> e.g. cpython-3.12.3-macos-aarch64-none
+Additionally, a specific system Python interpreter can often be requested with:
+
+<executable-path> e.g. /opt/homebrew/bin/python3<executable-name> e.g. mypython3<install-dir> e.g. /some/environment/
+When the --python option is used, normal discovery rules apply but discovered interpreters
+are checked for compatibility with the request, e.g., if pypy is requested, uv will first
+check if the virtual environment contains a PyPy interpreter then check if each executable
+in the path is a PyPy interpreter.
+uv supports discovering CPython, PyPy, and GraalPy interpreters. Unsupported interpreters
+will be skipped during discovery. If an unsupported interpreter implementation is requested,
+uv will exit with an error.
+Usage
+
+
+Commands
+
+uv python listList the available Python installations
uv python installDownload and install Python versions
uv python upgradeUpgrade installed Python versions
uv python findSearch for a Python installation
uv python pinPin to a specific Python version
uv python dirShow the uv Python installation directory
uv python uninstallUninstall Python versions
uv python update-shellEnsure that the Python executable directory is on the PATH
+
+uv python list
+List the available Python installations.
+By default, installed Python versions and the downloads for latest available patch version of each supported Python major version are shown.
+Use --managed-python to view only managed Python versions.
+Use --no-managed-python to omit managed Python versions.
+Use --all-versions to view all available patch versions.
+Use --only-installed to omit available downloads.
+Usage
+
+
+Arguments
+
+
+
+Options
+
+--all-arches, --all_architecturesList Python downloads for all architectures.
+By default, only downloads for the current architecture are shown.
+--all-platformsList Python downloads for all platforms.
+By default, only downloads for the current platform are shown.
+--all-versionsList all Python versions, including old patch versions.
+By default, only the latest patch version is shown for each minor version.
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--only-downloadsOnly show available Python downloads.
+By default, installed distributions and available downloads for the current platform are shown.
+--only-installedOnly show installed Python versions.
+By default, installed distributions and available downloads for the current platform are shown.
+--output-format output-formatSelect the output format
+[default: text]
Possible values:
+
+text: Plain text (for humans)json: JSON (for computers)
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python-downloads-json-url python-downloads-json-urlURL pointing to JSON of custom Python installations.
+Note that currently, only local paths are supported.
+--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--show-urlsShow the URLs of available Python downloads.
+By default, these display as <download available>.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv python install
+Download and install Python versions.
+Supports CPython and PyPy. CPython distributions are downloaded from the Astral python-build-standalone project. PyPy distributions are downloaded from python.org. The available Python versions are bundled with each uv release. To install new Python versions, you may need upgrade uv.
+Python versions are installed into the uv Python directory, which can be retrieved with uv python dir.
+By default, Python executables are added to a directory on the path with a minor version suffix, e.g., python3.13. To install python3 and python, use the --default flag. Use uv python dir --bin to see the target directory.
+Multiple Python versions may be requested.
+See uv help python to view supported request formats.
+Usage
+
+
+Arguments
+
+- TARGETS
The Python version(s) to install.
+If not provided, the requested Python version(s) will be read from the UV_PYTHON environment variable then .python-versions or .python-version files. If none of the above are present, uv will check if it has installed any Python versions. If not, it will install the latest stable version of Python.
+See uv python to view supported request formats.
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--defaultUse as the default Python version.
+By default, only a python{major}.{minor} executable is installed, e.g., python3.10. When the --default flag is used, python{major}, e.g., python3, and python executables are also installed.
+Alternative Python variants will still include their tag. For example, installing 3.13+freethreaded with --default will include in python3t and pythont, not python3 and python.
+If multiple Python versions are requested, uv will exit with an error.
+--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--force, -fReplace existing Python executables during installation.
+By default, uv will refuse to replace executables that it does not manage.
+Implies --reinstall.
+--help, -hDisplay the concise help for this command
+--install-dir, -i install-dirThe directory to store the Python installation in.
+If provided, UV_PYTHON_INSTALL_DIR will need to be set for subsequent operations for uv to discover the Python installation.
+See uv python dir to view the current Python installation directory. Defaults to ~/.local/share/uv/python.
+May also be set with the UV_PYTHON_INSTALL_DIR environment variable.
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--mirror mirrorSet the URL to use as the source for downloading Python installations.
+The provided URL will replace https://github.com/astral-sh/python-build-standalone/releases/download in, e.g., https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz.
+Distributions can be read from a local directory by using the file:// URL scheme.
+--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-binDo not install a Python executable into the bin directory.
+This can also be set with UV_PYTHON_INSTALL_BIN=0.
+--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-registryDo not register the Python installation in the Windows registry.
+This can also be set with UV_PYTHON_INSTALL_REGISTRY=0.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--pypy-mirror pypy-mirrorSet the URL to use as the source for downloading PyPy installations.
+The provided URL will replace https://downloads.python.org/pypy in, e.g., https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2.
+Distributions can be read from a local directory by using the file:// URL scheme.
+--python-downloads-json-url python-downloads-json-urlURL pointing to JSON of custom Python installations.
+Note that currently, only local paths are supported.
+--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--reinstall, -rReinstall the requested Python version, if it's already installed.
+By default, uv will exit successfully if the version is already installed.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv python upgrade
+Upgrade installed Python versions.
+Upgrades versions to the latest supported patch release. Requires the python-upgrade preview feature.
+A target Python minor version to upgrade may be provided, e.g., 3.13. Multiple versions may be provided to perform more than one upgrade.
+If no target version is provided, then uv will upgrade all managed CPython versions.
+During an upgrade, uv will not uninstall outdated patch versions.
+When an upgrade is performed, virtual environments created by uv will automatically use the new version. However, if the virtual environment was created before the upgrade functionality was added, it will continue to use the old Python version; to enable upgrades, the environment must be recreated.
+Upgrades are not yet supported for alternative implementations, like PyPy.
+Usage
+
+
+Arguments
+
+- TARGETS
The Python minor version(s) to upgrade.
+If no target version is provided, then uv will upgrade all managed CPython versions.
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--install-dir, -i install-dirThe directory Python installations are stored in.
+If provided, UV_PYTHON_INSTALL_DIR will need to be set for subsequent operations for uv to discover the Python installation.
+See uv python dir to view the current Python installation directory. Defaults to ~/.local/share/uv/python.
+May also be set with the UV_PYTHON_INSTALL_DIR environment variable.
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--mirror mirrorSet the URL to use as the source for downloading Python installations.
+The provided URL will replace https://github.com/astral-sh/python-build-standalone/releases/download in, e.g., https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz.
+Distributions can be read from a local directory by using the file:// URL scheme.
+--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--pypy-mirror pypy-mirrorSet the URL to use as the source for downloading PyPy installations.
+The provided URL will replace https://downloads.python.org/pypy in, e.g., https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2.
+Distributions can be read from a local directory by using the file:// URL scheme.
+--python-downloads-json-url python-downloads-json-urlURL pointing to JSON of custom Python installations.
+Note that currently, only local paths are supported.
+--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--reinstall, -rReinstall the latest Python patch, if it's already installed.
+By default, uv will exit successfully if the latest patch is already installed.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv python find
+Search for a Python installation.
+Displays the path to the Python executable.
+See uv help python to view supported request formats and details on discovery behavior.
+Usage
+
+
+Arguments
+
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-project, --no_workspaceAvoid discovering a project or workspace.
+Otherwise, when no request is provided, the Python requirement of a project in the current directory or parent directories will be used.
+--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--script scriptFind the environment for a Python script, rather than the current project
+--show-versionShow the Python version that would be used instead of the path to the interpreter
+--systemOnly find system Python interpreters.
+By default, uv will report the first Python interpreter it would use, including those in an active virtual environment or a virtual environment in the current working directory or any parent directory.
+The --system option instructs uv to skip virtual environment Python interpreters and restrict its search to the system path.
+May also be set with the UV_SYSTEM_PYTHON environment variable.
--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv python pin
+Pin to a specific Python version.
+Writes the pinned Python version to a .python-version file, which is used by other uv commands to determine the required Python version.
+If no version is provided, uv will look for an existing .python-version file and display the currently pinned version. If no .python-version file is found, uv will exit with an error.
+See uv help python to view supported request formats.
+Usage
+
+
+Arguments
+
+- REQUEST
The Python version request.
+uv supports more formats than other tools that read .python-version files, i.e., pyenv. If compatibility with those tools is needed, only use version numbers instead of complex requests such as cpython@3.10.
+If no request is provided, the currently pinned version will be shown.
+See uv python to view supported request formats.
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--globalUpdate the global Python version pin.
+Writes the pinned Python version to a .python-version file in the uv user configuration directory: XDG_CONFIG_HOME/uv on Linux/macOS and %APPDATA%/uv on Windows.
+When a local Python version pin is not found in the working directory or an ancestor directory, this version will be used instead.
+--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-project, --no-workspaceAvoid validating the Python pin is compatible with the project or workspace.
+By default, a project or workspace is discovered in the current directory or any parent directory. If a workspace is found, the Python pin is validated against the workspace's requires-python constraint.
+--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--resolvedWrite the resolved Python interpreter path instead of the request.
+Ensures that the exact same interpreter is used.
+This option is usually not safe to use when committing the .python-version file to version control.
+--rmRemove the Python version pin
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv python dir
+Show the uv Python installation directory.
+By default, Python installations are stored in the uv data directory at $XDG_DATA_HOME/uv/python or $HOME/.local/share/uv/python on Unix and %APPDATA%\uv\data\python on Windows.
+The Python installation directory may be overridden with $UV_PYTHON_INSTALL_DIR.
+To view the directory where uv installs Python executables instead, use the --bin flag. The Python executable directory may be overridden with $UV_PYTHON_BIN_DIR. Note that Python executables are only installed when preview mode is enabled.
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--binShow the directory into which uv python will install Python executables.
+Note that this directory is only used when installing Python with preview mode enabled.
+The Python executable directory is determined according to the XDG standard and is derived
+from the following environment variables, in order of preference:
+
+$UV_PYTHON_BIN_DIR$XDG_BIN_HOME$XDG_DATA_HOME/../bin$HOME/.local/bin
+--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv python uninstall
+Uninstall Python versions
+Usage
+
+
+Arguments
+
+
+
+Options
+
+--allUninstall all managed Python versions
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--install-dir, -i install-dirThe directory where the Python was installed
+May also be set with the UV_PYTHON_INSTALL_DIR environment variable.
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv python update-shell
+Ensure that the Python executable directory is on the PATH.
+If the Python executable directory is not present on the PATH, uv will attempt to add it to the relevant shell configuration files.
+If the shell configuration files already include a blurb to add the executable directory to the path, but the directory is not present on the PATH, uv will exit with an error.
+The Python executable directory is determined according to the XDG standard and can be retrieved with uv python dir --bin.
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv pip
+Manage Python packages with a pip-compatible interface
+Usage
+
+
+Commands
+
+uv pip compileCompile a requirements.in file to a requirements.txt or pylock.toml file
uv pip syncSync an environment with a requirements.txt or pylock.toml file
uv pip installInstall packages into an environment
uv pip uninstallUninstall packages from an environment
uv pip freezeList, in requirements format, packages installed in an environment
uv pip listList, in tabular format, packages installed in an environment
uv pip showShow information about one or more installed packages
uv pip treeDisplay the dependency tree for an environment
uv pip checkVerify installed packages have compatible dependencies
+
+uv pip compile
+Compile a requirements.in file to a requirements.txt or pylock.toml file
+Usage
+
+
+Arguments
+
+- SRC_FILE
Include the packages listed in the given files.
+The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.
+If a pyproject.toml, setup.py, or setup.cfg file is provided, uv will extract the requirements for the relevant project.
+If - is provided, then requirements will be read from stdin.
+The order of the requirements files and the requirements in them is used to determine priority during resolution.
+
+
+Options
+
+--all-extrasInclude all optional dependencies.
+Only applies to pyproject.toml, setup.py, and setup.cfg sources.
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--annotation-style annotation-styleThe style of the annotation comments included in the output file, used to indicate the source of each package.
+Defaults to split.
+Possible values:
+
+line: Render the annotations on a single, comma-separated linesplit: Render each annotation on its own line
--build-constraints, --build-constraint, -b build-constraintsConstrain build dependencies using the given requirements files when building source distributions.
+Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
+May also be set with the UV_BUILD_CONSTRAINT environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--constraints, --constraint, -c constraintsConstrain versions using the given requirements files.
+Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
+This is equivalent to pip's --constraint option.
+May also be set with the UV_CONSTRAINT environment variable.
--custom-compile-command custom-compile-commandThe 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.
+May also be set with the UV_CUSTOM_COMPILE_COMMAND environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--emit-build-optionsInclude --no-binary and --only-binary entries in the generated output file
+--emit-find-linksInclude --find-links entries in the generated output file
+--emit-index-annotationInclude comment annotations indicating the index used to resolve each package (e.g., # from https://pypi.org/simple)
+--emit-index-urlInclude --index-url and --extra-index-url entries in the generated output file
+--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for a specific package to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--excludes, --exclude excludesExclude packages from resolution using the given requirements files.
+Excludes files are requirements.txt-like files that specify packages to exclude from the resolution. When a package is excluded, it will be omitted from the dependency list entirely and its own dependencies will be ignored during the resolution phase. Excludes are unconditional in that requirement specifiers and markers are ignored; any package listed in the provided file will be omitted from all resolved environments.
+May also be set with the UV_EXCLUDE environment variable.
--extra extraInclude optional dependencies from the specified extra name; may be provided more than once.
+Only applies to pyproject.toml, setup.py, and setup.cfg sources.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
+May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
+
+fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--format formatThe format in which the resolution should be output.
+Supports both requirements.txt and pylock.toml (PEP 751) output formats.
+uv will infer the output format from the file extension of the output file, if provided. Otherwise, defaults to requirements.txt.
+Possible values:
+
+requirements.txt: Export in requirements.txt formatpylock.toml: Export in pylock.toml format
--generate-hashesInclude distribution hashes in the output file
+--group groupInstall the specified dependency group from a pyproject.toml.
+If no path is provided, the pyproject.toml in the working directory is used.
+May be provided multiple times.
+--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+This option is only used when building source distributions.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-annotateExclude comment annotations indicating the source of each package
+--no-binary no-binaryDon'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:.
+--no-buildDon'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:.
+--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518 are already installed.
+--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-depsIgnore package dependencies, instead only add those packages explicitly listed on the command line to the resulting requirements file
+--no-emit-package, --unsafe-package no-emit-packageSpecify 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
+--no-headerExclude the comment header at the top of the generated output file
+--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--no-strip-extrasInclude 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.
+--no-strip-markersInclude environment markers in the output file.
+By default, uv strips environment markers, as the resolution generated by compile is only guaranteed to be correct for the target environment.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--only-binary only-binaryOnly 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:.
+--output-file, -o output-fileWrite the compiled requirements to the given requirements.txt or pylock.toml file.
+If the file already exists, the existing versions will be preferred when resolving dependencies, unless --upgrade is also specified.
+--overrides, --override overridesOverride versions using the given requirements files.
+Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.
+While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.
+May also be set with the UV_OVERRIDE environment variable.
--prerelease prereleaseThe 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).
+May also be set with the UV_PRERELEASE environment variable.
Possible values:
+
+disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use during resolution.
+A Python interpreter is required for building source distributions to determine package
+metadata when there are not wheels.
+The interpreter is also used to determine the default minimum Python version, unless
+--python-version is provided.
+This option respects UV_PYTHON, but when set via environment variable, it is overridden
+by --python-version.
+See uv python for details on Python discovery and supported request formats.
+--python-platform python-platformThe 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.
+When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
+Possible values:
+
+windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--python-version python-versionThe Python version to use for resolution.
+For example, 3.8 or 3.8.17.
+Defaults to the version of the Python interpreter used for resolution.
+Defines the minimum Python version that must be supported by the resolved requirements.
+If a patch version is omitted, the minimum patch version is assumed. For example, 3.8 is mapped to 3.8.0.
+--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--refreshRefresh all cached data
+--refresh-package refresh-packageRefresh cached data for a specific package
+--resolution resolutionThe 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).
+May also be set with the UV_RESOLUTION environment variable.
Possible values:
+
+highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--systemInstall packages into the system Python environment.
+By default, uv uses the virtual environment in the current working directory or any parent directory, falling back to searching for a Python executable in PATH. The --system option instructs uv to avoid using a virtual environment Python and restrict its search to the system path.
+May also be set with the UV_SYSTEM_PYTHON environment variable.
--torch-backend torch-backendThe backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto).
+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 option is in preview and may change in any future release.
+May also be set with the UV_TORCH_BACKEND environment variable.
Possible values:
+
+auto: Select the appropriate PyTorch index based on the operating system and CUDA driver versioncpu: Use the CPU-only PyTorch indexcu130: Use the PyTorch index for CUDA 13.0cu129: Use the PyTorch index for CUDA 12.9cu128: Use the PyTorch index for CUDA 12.8cu126: Use the PyTorch index for CUDA 12.6cu125: Use the PyTorch index for CUDA 12.5cu124: Use the PyTorch index for CUDA 12.4cu123: Use the PyTorch index for CUDA 12.3cu122: Use the PyTorch index for CUDA 12.2cu121: Use the PyTorch index for CUDA 12.1cu120: Use the PyTorch index for CUDA 12.0cu118: Use the PyTorch index for CUDA 11.8cu117: Use the PyTorch index for CUDA 11.7cu116: Use the PyTorch index for CUDA 11.6cu115: Use the PyTorch index for CUDA 11.5cu114: Use the PyTorch index for CUDA 11.4cu113: Use the PyTorch index for CUDA 11.3cu112: Use the PyTorch index for CUDA 11.2cu111: Use the PyTorch index for CUDA 11.1cu110: Use the PyTorch index for CUDA 11.0cu102: Use the PyTorch index for CUDA 10.2cu101: Use the PyTorch index for CUDA 10.1cu100: Use the PyTorch index for CUDA 10.0cu92: Use the PyTorch index for CUDA 9.2cu91: Use the PyTorch index for CUDA 9.1cu90: Use the PyTorch index for CUDA 9.0cu80: Use the PyTorch index for CUDA 8.0rocm6.3: Use the PyTorch index for ROCm 6.3rocm6.2.4: Use the PyTorch index for ROCm 6.2.4rocm6.2: Use the PyTorch index for ROCm 6.2rocm6.1: Use the PyTorch index for ROCm 6.1rocm6.0: Use the PyTorch index for ROCm 6.0rocm5.7: Use the PyTorch index for ROCm 5.7rocm5.6: Use the PyTorch index for ROCm 5.6rocm5.5: Use the PyTorch index for ROCm 5.5rocm5.4.2: Use the PyTorch index for ROCm 5.4.2rocm5.4: Use the PyTorch index for ROCm 5.4rocm5.3: Use the PyTorch index for ROCm 5.3rocm5.2: Use the PyTorch index for ROCm 5.2rocm5.1.1: Use the PyTorch index for ROCm 5.1.1rocm4.2: Use the PyTorch index for ROCm 4.2rocm4.1: Use the PyTorch index for ROCm 4.1rocm4.0.1: Use the PyTorch index for ROCm 4.0.1xpu: Use the PyTorch index for Intel XPU
--universalPerform 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.
+Implies --no-strip-markers.
+--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
+--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv pip sync
+Sync an environment with a requirements.txt or pylock.toml file.
+When syncing an environment, any packages not listed in the requirements.txt or pylock.toml file will be removed. To retain extraneous packages, use uv pip install instead.
+The input file is presumed to be the output of a pip compile or uv export operation, in which it will include all transitive dependencies. If transitive dependencies are not present in the file, they will not be installed. Use --strict to warn if any transitive dependencies are missing.
+Usage
+
+
+Arguments
+
+- SRC_FILE
Include the packages listed in the given files.
+The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.
+If a pyproject.toml, setup.py, or setup.cfg file is provided, uv will extract the requirements for the relevant project.
+If - is provided, then requirements will be read from stdin.
+
+
+Options
+
+--all-extrasInclude all optional dependencies.
+Only applies to pylock.toml, pyproject.toml, setup.py, and setup.cfg sources.
+--allow-empty-requirementsAllow sync of empty requirements, which will clear the environment of all packages
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--break-system-packagesAllow 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).
+May also be set with the UV_BREAK_SYSTEM_PACKAGES environment variable.
--build-constraints, --build-constraint, -b build-constraintsConstrain build dependencies using the given requirements files when building source distributions.
+Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
+May also be set with the UV_BUILD_CONSTRAINT environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
+May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--constraints, --constraint, -c constraintsConstrain versions using the given requirements files.
+Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
+This is equivalent to pip's --constraint option.
+May also be set with the UV_CONSTRAINT environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runPerform a dry run, i.e., don't actually install anything but resolve the dependencies and print the resulting plan
+--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--extra extraInclude optional dependencies from the specified extra name; may be provided more than once.
+Only applies to pylock.toml, pyproject.toml, setup.py, and setup.cfg sources.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--group groupInstall the specified dependency group from a pylock.toml or pyproject.toml.
+If no path is provided, the pylock.toml or pyproject.toml in the working directory is used.
+May be provided multiple times.
+--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-allow-empty-requirements--no-binary no-binaryDon'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:.
+--no-break-system-packages--no-buildDon'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:.
+--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--no-verify-hashesDisable validation of hashes in the requirements file.
+By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash. To enforce hash validation, use --require-hashes.
+May also be set with the UV_NO_VERIFY_HASHES environment variable.
--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--only-binary only-binaryOnly 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:.
+--prefix prefixInstall 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.
+--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter into which packages should be installed.
+By default, syncing requires a virtual environment. A path to an alternative Python can be
+provided, but it is only recommended in continuous integration (CI) environments and should
+be used with caution, as it can modify the system Python installation.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which requirements should be installed.
+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.
+When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
+WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.
+Possible values:
+
+windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--python-version python-versionThe minimum Python version that should be supported by the requirements (e.g., 3.7 or 3.7.9).
+If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.
+--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--refreshRefresh all cached data
+--refresh-package refresh-packageRefresh cached data for a specific package
+--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
+--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
+--require-hashesRequire a matching hash for each requirement.
+By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash.
+When --require-hashes is enabled, all requirements must include a hash or set of hashes, and 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.
+
+May also be set with the UV_REQUIRE_HASHES environment variable.
--strictValidate the Python environment after completing the installation, to detect packages with missing dependencies or other issues
+--systemInstall 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.
+May also be set with the UV_SYSTEM_PYTHON environment variable.
--target targetInstall 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
+--torch-backend torch-backendThe backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto).
+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 option is in preview and may change in any future release.
+May also be set with the UV_TORCH_BACKEND environment variable.
Possible values:
+
+auto: Select the appropriate PyTorch index based on the operating system and CUDA driver versioncpu: Use the CPU-only PyTorch indexcu130: Use the PyTorch index for CUDA 13.0cu129: Use the PyTorch index for CUDA 12.9cu128: Use the PyTorch index for CUDA 12.8cu126: Use the PyTorch index for CUDA 12.6cu125: Use the PyTorch index for CUDA 12.5cu124: Use the PyTorch index for CUDA 12.4cu123: Use the PyTorch index for CUDA 12.3cu122: Use the PyTorch index for CUDA 12.2cu121: Use the PyTorch index for CUDA 12.1cu120: Use the PyTorch index for CUDA 12.0cu118: Use the PyTorch index for CUDA 11.8cu117: Use the PyTorch index for CUDA 11.7cu116: Use the PyTorch index for CUDA 11.6cu115: Use the PyTorch index for CUDA 11.5cu114: Use the PyTorch index for CUDA 11.4cu113: Use the PyTorch index for CUDA 11.3cu112: Use the PyTorch index for CUDA 11.2cu111: Use the PyTorch index for CUDA 11.1cu110: Use the PyTorch index for CUDA 11.0cu102: Use the PyTorch index for CUDA 10.2cu101: Use the PyTorch index for CUDA 10.1cu100: Use the PyTorch index for CUDA 10.0cu92: Use the PyTorch index for CUDA 9.2cu91: Use the PyTorch index for CUDA 9.1cu90: Use the PyTorch index for CUDA 9.0cu80: Use the PyTorch index for CUDA 8.0rocm6.3: Use the PyTorch index for ROCm 6.3rocm6.2.4: Use the PyTorch index for ROCm 6.2.4rocm6.2: Use the PyTorch index for ROCm 6.2rocm6.1: Use the PyTorch index for ROCm 6.1rocm6.0: Use the PyTorch index for ROCm 6.0rocm5.7: Use the PyTorch index for ROCm 5.7rocm5.6: Use the PyTorch index for ROCm 5.6rocm5.5: Use the PyTorch index for ROCm 5.5rocm5.4.2: Use the PyTorch index for ROCm 5.4.2rocm5.4: Use the PyTorch index for ROCm 5.4rocm5.3: Use the PyTorch index for ROCm 5.3rocm5.2: Use the PyTorch index for ROCm 5.2rocm5.1.1: Use the PyTorch index for ROCm 5.1.1rocm4.2: Use the PyTorch index for ROCm 4.2rocm4.1: Use the PyTorch index for ROCm 4.1rocm4.0.1: Use the PyTorch index for ROCm 4.0.1xpu: Use the PyTorch index for Intel XPU
--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv pip install
+Install packages into an environment
+Usage
+
+uv pip install [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>|--editable <EDITABLE>|--group <GROUP>>
+
+Arguments
+
+- PACKAGE
Install all listed packages.
+The order of the packages is used to determine priority during resolution.
+
+
+Options
+
+--all-extrasInclude all optional dependencies.
+Only applies to pylock.toml, pyproject.toml, setup.py, and setup.cfg sources.
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--break-system-packagesAllow 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).
+May also be set with the UV_BREAK_SYSTEM_PACKAGES environment variable.
--build-constraints, --build-constraint, -b build-constraintsConstrain build dependencies using the given requirements files when building source distributions.
+Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
+May also be set with the UV_BUILD_CONSTRAINT environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
+May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--constraints, --constraint, -c constraintsConstrain versions using the given requirements files.
+Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
+This is equivalent to pip's --constraint option.
+May also be set with the UV_CONSTRAINT environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runPerform a dry run, i.e., don't actually install anything but resolve the dependencies and print the resulting plan
+--editable, -e editableInstall the editable package based on the provided local file path
+--exactPerform an exact sync, removing extraneous packages.
+By default, installing will make the minimum necessary changes to satisfy the requirements. When enabled, uv will update the environment to exactly match the requirements, removing packages that are not included in the requirements.
+--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--excludes, --exclude excludesExclude packages from resolution using the given requirements files.
+Excludes files are requirements.txt-like files that specify packages to exclude from the resolution. When a package is excluded, it will be omitted from the dependency list entirely and its own dependencies will be ignored during the resolution phase. Excludes are unconditional in that requirement specifiers and markers are ignored; any package listed in the provided file will be omitted from all resolved environments.
+May also be set with the UV_EXCLUDE environment variable.
--extra extraInclude optional dependencies from the specified extra name; may be provided more than once.
+Only applies to pylock.toml, pyproject.toml, setup.py, and setup.cfg sources.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
+May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
+
+fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--group groupInstall the specified dependency group from a pylock.toml or pyproject.toml.
+If no path is provided, the pylock.toml or pyproject.toml in the working directory is used.
+May be provided multiple times.
+--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-binary no-binaryDon'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:.
+--no-break-system-packages--no-buildDon'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:.
+--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518 are already installed.
+--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-depsIgnore package dependencies, instead only installing those packages explicitly listed on the command line or in the requirements files
+--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--no-verify-hashesDisable validation of hashes in the requirements file.
+By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash. To enforce hash validation, use --require-hashes.
+May also be set with the UV_NO_VERIFY_HASHES environment variable.
--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--only-binary only-binaryOnly 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:.
+--overrides, --override overridesOverride versions using the given requirements files.
+Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.
+While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.
+May also be set with the UV_OVERRIDE environment variable.
--prefix prefixInstall 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.
+--prerelease prereleaseThe 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).
+May also be set with the UV_PRERELEASE environment variable.
Possible values:
+
+disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter into which packages should be installed.
+By default, installation requires a virtual environment. A path to an alternative Python can
+be provided, but it is only recommended in continuous integration (CI) environments and
+should be used with caution, as it can modify the system Python installation.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which requirements should be installed.
+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.
+When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
+WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.
+Possible values:
+
+windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--python-version python-versionThe minimum Python version that should be supported by the requirements (e.g., 3.7 or 3.7.9).
+If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.
+--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--refreshRefresh all cached data
+--refresh-package refresh-packageRefresh cached data for a specific package
+--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
+--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
+--require-hashesRequire a matching hash for each requirement.
+By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash.
+When --require-hashes is enabled, all requirements must include a hash or set of hashes, and 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.
+
+May also be set with the UV_REQUIRE_HASHES environment variable.
--requirements, --requirement, -r requirementsInstall the packages listed in the given files.
+The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.
+If a pyproject.toml, setup.py, or setup.cfg file is provided, uv will extract the requirements for the relevant project.
+If - is provided, then requirements will be read from stdin.
+--resolution resolutionThe 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).
+May also be set with the UV_RESOLUTION environment variable.
Possible values:
+
+highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--strictValidate the Python environment after completing the installation, to detect packages with missing dependencies or other issues
+--systemInstall 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.
+May also be set with the UV_SYSTEM_PYTHON environment variable.
--target targetInstall 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
+--torch-backend torch-backendThe backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto)
+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 option is in preview and may change in any future release.
+May also be set with the UV_TORCH_BACKEND environment variable.
Possible values:
+
+auto: Select the appropriate PyTorch index based on the operating system and CUDA driver versioncpu: Use the CPU-only PyTorch indexcu130: Use the PyTorch index for CUDA 13.0cu129: Use the PyTorch index for CUDA 12.9cu128: Use the PyTorch index for CUDA 12.8cu126: Use the PyTorch index for CUDA 12.6cu125: Use the PyTorch index for CUDA 12.5cu124: Use the PyTorch index for CUDA 12.4cu123: Use the PyTorch index for CUDA 12.3cu122: Use the PyTorch index for CUDA 12.2cu121: Use the PyTorch index for CUDA 12.1cu120: Use the PyTorch index for CUDA 12.0cu118: Use the PyTorch index for CUDA 11.8cu117: Use the PyTorch index for CUDA 11.7cu116: Use the PyTorch index for CUDA 11.6cu115: Use the PyTorch index for CUDA 11.5cu114: Use the PyTorch index for CUDA 11.4cu113: Use the PyTorch index for CUDA 11.3cu112: Use the PyTorch index for CUDA 11.2cu111: Use the PyTorch index for CUDA 11.1cu110: Use the PyTorch index for CUDA 11.0cu102: Use the PyTorch index for CUDA 10.2cu101: Use the PyTorch index for CUDA 10.1cu100: Use the PyTorch index for CUDA 10.0cu92: Use the PyTorch index for CUDA 9.2cu91: Use the PyTorch index for CUDA 9.1cu90: Use the PyTorch index for CUDA 9.0cu80: Use the PyTorch index for CUDA 8.0rocm6.3: Use the PyTorch index for ROCm 6.3rocm6.2.4: Use the PyTorch index for ROCm 6.2.4rocm6.2: Use the PyTorch index for ROCm 6.2rocm6.1: Use the PyTorch index for ROCm 6.1rocm6.0: Use the PyTorch index for ROCm 6.0rocm5.7: Use the PyTorch index for ROCm 5.7rocm5.6: Use the PyTorch index for ROCm 5.6rocm5.5: Use the PyTorch index for ROCm 5.5rocm5.4.2: Use the PyTorch index for ROCm 5.4.2rocm5.4: Use the PyTorch index for ROCm 5.4rocm5.3: Use the PyTorch index for ROCm 5.3rocm5.2: Use the PyTorch index for ROCm 5.2rocm5.1.1: Use the PyTorch index for ROCm 5.1.1rocm4.2: Use the PyTorch index for ROCm 4.2rocm4.1: Use the PyTorch index for ROCm 4.1rocm4.0.1: Use the PyTorch index for ROCm 4.0.1xpu: Use the PyTorch index for Intel XPU
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
+--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
+--user--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv pip uninstall
+Uninstall packages from an environment
+Usage
+
+
+Arguments
+
+- PACKAGE
Uninstall all listed packages
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--break-system-packagesAllow 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).
+May also be set with the UV_BREAK_SYSTEM_PACKAGES environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runPerform a dry run, i.e., don't actually uninstall anything but print the resulting plan
+--help, -hDisplay the concise help for this command
+--keyring-provider keyring-providerAttempt to use keyring for authentication for remote requirements files.
+At present, only --keyring-provider subprocess is supported, which configures uv to use the keyring CLI to handle authentication.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-break-system-packages--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--prefix prefixUninstall packages from the specified --prefix directory
+--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter from which packages should be uninstalled.
+By default, uninstallation requires a virtual environment. A path to an alternative Python
+can be provided, but it is only recommended in continuous integration (CI) environments and
+should be used with caution, as it can modify the system Python installation.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--requirements, --requirement, -r requirementsUninstall the packages listed in the given files.
+The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.
+--systemUse the system Python to uninstall packages.
+By default, uv uninstalls from 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.
+May also be set with the UV_SYSTEM_PYTHON environment variable.
--target targetUninstall packages from the specified --target directory
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv pip freeze
+List, in requirements format, packages installed in an environment
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-editableExclude any editable packages from output
+--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--path pathsRestrict to the specified installation path for listing packages (can be used multiple times)
+--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter for which packages should be listed.
+By default, uv lists packages in a virtual environment but will show packages in a system
+Python environment if no virtual environment is found.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--strictValidate the Python environment, to detect packages with missing dependencies and other issues
+--systemList packages in the system Python environment.
+Disables discovery of virtual environments.
+See uv python for details on Python discovery.
+May also be set with the UV_SYSTEM_PYTHON environment variable.
--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv pip list
+List, in tabular format, packages installed in an environment
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--editable, -eOnly include editable projects
+--exclude excludeExclude the specified package(s) from the output
+--exclude-editableExclude any editable packages from output
+--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--format formatSelect the output format
+[default: columns]
Possible values:
+
+columns: Display the list of packages in a human-readable tablefreeze: Display the list of packages in a pip freeze-like format, with one package per line alongside its versionjson: Display the list of packages in a machine-readable JSON format
--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--outdatedList outdated packages.
+The latest version of each package will be shown alongside the installed version. Up-to-date packages will be omitted from the output.
+--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter for which packages should be listed.
+By default, uv lists packages in a virtual environment but will show packages in a system
+Python environment if no virtual environment is found.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--strictValidate the Python environment, to detect packages with missing dependencies and other issues
+--systemList packages in the system Python environment.
+Disables discovery of virtual environments.
+See uv python for details on Python discovery.
+May also be set with the UV_SYSTEM_PYTHON environment variable.
--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv pip show
+Show information about one or more installed packages
+Usage
+
+
+Arguments
+
+- PACKAGE
The package(s) to display
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--files, -fShow the full list of installed files for each package
+--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to find the package in.
+By default, uv looks for packages in a virtual environment but will look for packages in a
+system Python environment if no virtual environment is found.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--strictValidate the Python environment, to detect packages with missing dependencies and other issues
+--systemShow a package in the system Python environment.
+Disables discovery of virtual environments.
+See uv python for details on Python discovery.
+May also be set with the UV_SYSTEM_PYTHON environment variable.
--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv pip tree
+Display the dependency tree for an environment
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--depth, -d depthMaximum display depth of the dependency tree
+[default: 255]
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--invert, --reverseShow the reverse dependencies for the given package. This flag will invert the tree and display the packages that depend on the given package
+--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-dedupeDo not de-duplicate repeated dependencies. Usually, when a package has already displayed its dependencies, further occurrences will not re-display its dependencies, and will include a (*) to indicate it has already been shown. This flag will cause those duplicates to be repeated
+--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--outdatedShow the latest available version of each package in the tree
+--package packageDisplay only the specified packages
+--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--prune prunePrune the given package from the display of the dependency tree
+--python, -p pythonThe Python interpreter for which packages should be listed.
+By default, uv lists packages in a virtual environment but will show packages in a system
+Python environment if no virtual environment is found.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--show-sizesShow compressed wheel sizes for packages in the tree
+--show-version-specifiersShow the version constraint(s) imposed on each package
+--strictValidate the Python environment, to detect packages with missing dependencies and other issues
+--systemList packages in the system Python environment.
+Disables discovery of virtual environments.
+See uv python for details on Python discovery.
+May also be set with the UV_SYSTEM_PYTHON environment variable.
--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv pip check
+Verify installed packages have compatible dependencies
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter for which packages should be checked.
+By default, uv checks packages in a virtual environment but will check packages in a system
+Python environment if no virtual environment is found.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which packages should be checked.
+By default, the installed packages are checked against the platform of the current interpreter.
+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.
+When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
+When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
+Possible values:
+
+windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--python-version python-versionThe Python version against which packages should be checked.
+By default, the installed packages are checked against the version of the current interpreter.
+--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--systemCheck packages in the system Python environment.
+Disables discovery of virtual environments.
+See uv python for details on Python discovery.
+May also be set with the UV_SYSTEM_PYTHON environment variable.
--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv venv
+Create a virtual environment.
+By default, creates a virtual environment named .venv in the working directory. An alternative path may be provided positionally.
+If in a project, the default environment name can be changed with the UV_PROJECT_ENVIRONMENT environment variable; this only applies when run from the project root directory.
+If a virtual environment exists at the target path, it will be removed and a new, empty virtual environment will be created.
+When using uv, the virtual environment does not need to be activated. uv will find a virtual environment (named .venv) in the working directory or any parent directories.
+Usage
+
+
+Arguments
+
+- PATH
The path to the virtual environment to create.
+Default to .venv in the working directory.
+Relative paths are resolved relative to the working directory.
+
+
+Options
+
+--allow-existingPreserve any existing files or directories at the target path.
+By default, uv venv will exit with an error if the given path is non-empty. The --allow-existing option will instead write to the given path, regardless of its contents, and without clearing it beforehand.
+WARNING: This option can lead to unexpected behavior if the existing virtual environment and the newly-created virtual environment are linked to different Python interpreters.
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--clear, -cRemove any existing files or directories at the target path.
+By default, uv venv will exit with an error if the given path is non-empty. The --clear option will instead clear a non-empty path before creating a new virtual environment.
+May also be set with the UV_VENV_CLEAR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for a specific package to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+This option is only used for installing seed packages.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-project, --no-workspaceAvoid discovering a project or workspace.
+By default, uv searches for projects in the current directory or any parent directory to determine the default path of the virtual environment and check for Python version constraints, if any.
+--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--prompt promptProvide an alternative prompt prefix for the virtual environment.
+By default, the prompt is dependent on whether a path was provided to uv venv. If provided
+(e.g, uv venv project), the prompt is set to the directory name. If not provided
+(uv venv), the prompt is set to the current directory's name.
+If "." is provided, the current directory name will be used regardless of whether a path was
+provided to uv venv.
+--python, -p pythonThe Python interpreter to use for the virtual environment.
+During virtual environment creation, uv will not look for Python interpreters in virtual
+environments.
+See uv python for details on Python discovery and supported request formats.
+May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--refreshRefresh all cached data
+--refresh-package refresh-packageRefresh cached data for a specific package
+--relocatableMake the virtual environment relocatable.
+A relocatable virtual environment can be moved around and redistributed without invalidating its associated entrypoint and activation scripts.
+Note that this can only be guaranteed for standard console_scripts and gui_scripts. Other scripts may be adjusted if they ship with a generic #!python[w] shebang, and binaries are left as-is.
+As a result of making the environment relocatable (by way of writing relative, rather than absolute paths), the entrypoints and scripts themselves will not be relocatable. In other words, copying those entrypoints and scripts to a location outside the environment will not work, as they reference paths relative to the environment itself.
+--seedInstall seed packages (one or more of: pip, setuptools, and wheel) into the virtual environment.
+Note that setuptools and wheel are not included in Python 3.12+ environments.
+May also be set with the UV_VENV_SEED environment variable.
--system-site-packagesGive the virtual environment access to the system site packages directory.
+Unlike pip, when a virtual environment is created with --system-site-packages, uv will not take system site packages into account when running commands like uv pip list or uv pip install. The --system-site-packages flag will provide the virtual environment with access to the system site packages directory at runtime, but will not affect the behavior of uv commands.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv build
+Build Python packages into source distributions and wheels.
+uv build accepts a path to a directory or source distribution, which defaults to the current working directory.
+By default, if passed a directory, uv build will build a source distribution ("sdist") from the source directory, and a binary distribution ("wheel") from the source distribution.
+uv build --sdist can be used to build only the source distribution, uv build --wheel can be used to build only the binary distribution, and uv build --sdist --wheel can be used to build both distributions from source.
+If passed a source distribution, uv build --wheel will build a wheel from the source distribution.
+Usage
+
+
+Arguments
+
+- SRC
The directory from which distributions should be built, or a source distribution archive to build into a wheel.
+Defaults to the current working directory.
+
+
+Options
+
+--all-packages, --allBuilds all packages in the workspace.
+The workspace will be discovered from the provided source directory, or the current directory if no source directory is provided.
+If the workspace member does not exist, uv will exit with an error.
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--build-constraints, --build-constraint, -b build-constraintsConstrain build dependencies using the given requirements files when building distributions.
+Constraints files are requirements.txt-like files that only control the version of a build dependency that's installed. However, including a package in a constraints file will not trigger the inclusion of that package on its own.
+May also be set with the UV_BUILD_CONSTRAINT environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--clearClear the output directory before the build, removing stale artifacts
+--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
+--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
+--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
+May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
+Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
+May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for a specific package to those that were uploaded prior to the given date.
+Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
+Can be provided multiple times for different packages.
+--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
+May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
+May also be set with the UV_FIND_LINKS environment variable.
--force-pep517Always build through PEP 517, don't use the fast path for the uv build backend.
+By default, uv won't create a PEP 517 build environment for packages using the uv build backend, but use a fast path that calls into the build backend directly. This option forces always using PEP 517.
+--fork-strategy fork-strategyThe 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.
+May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
+
+fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--help, -hDisplay the concise help for this command
+--index indexThe URLs to use when resolving dependencies, in addition to the default index.
+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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
+Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.
+May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
+May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
+
+first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
+May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
+This option is only used when building source distributions.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
+May also be set with the UV_LINK_MODE environment variable.
Possible values:
+
+clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
+May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
+May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
+May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518 are already installed.
+May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518 are already installed.
+--no-build-logsHide logs from the build backend
+--no-build-package no-build-packageDon't build source distributions for a specific package
+May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-create-gitignoreDo not create a .gitignore file in the output directory.
+By default, uv creates a .gitignore file in the output directory to exclude build artifacts from version control. When this flag is used, the file will be omitted.
+--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
+--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
+May also be set with the UV_NO_SOURCES environment variable.
--no-verify-hashesDisable validation of hashes in the requirements file.
+By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash. To enforce hash validation, use --require-hashes.
+May also be set with the UV_NO_VERIFY_HASHES environment variable.
--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--out-dir, -o out-dirThe output directory to which distributions should be written.
+Defaults to the dist subdirectory within the source directory, or the directory containing the source distribution archive.
+--package packageBuild a specific package in the workspace.
+The workspace will be discovered from the provided source directory, or the current directory if no source directory is provided.
+If the workspace member does not exist, uv will exit with an error.
+--prerelease prereleaseThe 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).
+May also be set with the UV_PRERELEASE environment variable.
Possible values:
+
+disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use for the build environment.
+By default, builds are executed in isolated virtual environments. The discovered interpreter
+will be used to create those environments, and will be symlinked or copied in depending on
+the platform.
+See uv python to view supported request formats.
+May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--refreshRefresh all cached data
+--refresh-package refresh-packageRefresh cached data for a specific package
+--require-hashesRequire a matching hash for each requirement.
+By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash.
+When --require-hashes is enabled, all requirements must include a hash or set of hashes, and 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.
+
+May also be set with the UV_REQUIRE_HASHES environment variable.
--resolution resolutionThe 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).
+May also be set with the UV_RESOLUTION environment variable.
Possible values:
+
+highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--sdistBuild a source distribution ("sdist") from the given directory
+--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
+--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+--wheelBuild a binary distribution ("wheel") from the given directory
+
+
+uv publish
+Upload distributions to an index
+Usage
+
+
+Arguments
+
+- FILES
Paths to the files to upload. Accepts glob expressions.
+Defaults to the dist directory. Selects only wheels and source distributions, while ignoring other files.
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--check-url check-urlCheck an index URL for existing files to skip duplicate uploads.
+This option allows retrying publishing that failed after only some, but not all files have been uploaded, and handles errors due to parallel uploads of the same file.
+Before uploading, the index is checked. If the exact same file already exists in the index, the file will not be uploaded. If an error occurred during the upload, the index is checked again, to handle cases where the identical file was uploaded twice in parallel.
+The exact behavior will vary based on the index. When uploading to PyPI, uploading the same file succeeds even without --check-url, while most other indexes error. When uploading to pyx, the index URL can be inferred automatically from the publish URL.
+The index must provide one of the supported hashes (SHA-256, SHA-384, or SHA-512).
+May also be set with the UV_PUBLISH_CHECK_URL environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runPerform a dry run without uploading files.
+When enabled, the command will check for existing files if --check-url is provided, and will perform validation against the index if supported, but will not upload any files.
+--help, -hDisplay the concise help for this command
+--index indexThe name of an index in the configuration to use for publishing.
+The index must have a publish-url setting, for example:
+[[tool.uv.index]]
+name = "pypi"
+url = "https://pypi.org/simple"
+publish-url = "https://upload.pypi.org/legacy/"
+
+The index url will be used to check for existing files to skip duplicate uploads.
+With these settings, the following two calls are equivalent:
+uv publish --index pypi
+uv publish --publish-url https://upload.pypi.org/legacy/ --check-url https://pypi.org/simple
+
+May also be set with the UV_PUBLISH_INDEX environment variable.
--keyring-provider keyring-providerAttempt to use keyring for authentication for remote requirements files.
+At present, only --keyring-provider subprocess is supported, which configures uv to use the keyring CLI to handle authentication.
+Defaults to disabled.
+May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
+
+disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--password, -p passwordThe password for the upload
+May also be set with the UV_PUBLISH_PASSWORD environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--publish-url publish-urlThe URL of the upload endpoint (not the index URL).
+Note that there are typically different URLs for index access (e.g., https:://.../simple) and index upload.
+Defaults to PyPI's publish URL (https://upload.pypi.org/legacy/).
+May also be set with the UV_PUBLISH_URL environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--token, -t tokenThe token for the upload.
+Using a token is equivalent to passing __token__ as --username and the token as --password password.
+May also be set with the UV_PUBLISH_TOKEN environment variable.
--trusted-publishing trusted-publishingConfigure trusted publishing.
+By default, uv checks for trusted publishing when running in a supported environment, but ignores it if it isn't configured.
+uv's supported environments for trusted publishing include GitHub Actions and GitLab CI/CD.
+Possible values:
+
+automatic: Attempt trusted publishing when we're in a supported environment, continue if that failsalwaysnever
--username, -u usernameThe username for the upload
+May also be set with the UV_PUBLISH_USERNAME environment variable.
--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv cache
+Manage uv's cache
+Usage
+
+
+Commands
+
+uv cache cleanClear the cache, removing all entries or those linked to specific packages
uv cache prunePrune all unreachable objects from the cache
uv cache dirShow the cache directory
uv cache sizeShow the cache size
+
+uv cache clean
+Clear the cache, removing all entries or those linked to specific packages
+Usage
+
+
+Arguments
+
+- PACKAGE
The packages to remove from the cache
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--forceForce removal of the cache, ignoring in-use checks.
+By default, uv cache clean will block until no process is reading the cache. When --force is used, uv cache clean will proceed without taking a lock.
+--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv cache prune
+Prune all unreachable objects from the cache
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--ciOptimize the cache for persistence in a continuous integration environment, like GitHub Actions.
+By default, uv caches both the wheels that it builds from source and the pre-built wheels that it downloads directly, to enable high-performance package installation. In some scenarios, though, persisting pre-built wheels may be undesirable. For example, in GitHub Actions, it's faster to omit pre-built wheels from the cache and instead have re-download them on each run. However, it typically is faster to cache wheels that are built from source, since the wheel building process can be expensive, especially for extension modules.
+In --ci mode, uv will prune any pre-built wheels from the cache, but retain any wheels that were built from source.
+--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--forceForce removal of the cache, ignoring in-use checks.
+By default, uv cache prune will block until no process is reading the cache. When --force is used, uv cache prune will proceed without taking a lock.
+--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv cache dir
+Show the cache directory.
+By default, the cache is stored in $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Unix and %LOCALAPPDATA%\uv\cache on Windows.
+When --no-cache is used, the cache is stored in a temporary directory and discarded when the process exits.
+An alternative cache directory may be specified via the cache-dir setting, the --cache-dir option, or the $UV_CACHE_DIR environment variable.
+Note that it is important for performance for the cache directory to be located on the same file system as the Python environment uv is operating on.
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv cache size
+Show the cache size.
+Displays the total size of the cache directory. This includes all downloaded and built wheels, source distributions, and other cached data. By default, outputs the size in raw bytes; use --human for human-readable output.
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--human, --human-readable, -HDisplay the cache size in human-readable format (e.g., 1.2 GiB instead of raw bytes)
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv self
+Manage the uv executable
+Usage
+
+
+Commands
+
+uv self updateUpdate uv
uv self versionDisplay uv's version
+
+uv self update
+Update uv
+Usage
+
+
+Arguments
+
+- TARGET_VERSION
Update to the specified version. If not provided, uv will update to the latest version
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runRun without performing the update
+--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--token tokenA GitHub token for authentication. A token is not required but can be used to reduce the chance of encountering rate limits
+May also be set with the UV_GITHUB_TOKEN environment variable.
--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv self version
+Display uv's version
+Usage
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--output-format output-format--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--shortOnly print the version
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+uv generate-shell-completion
+Generate shell completion
+Usage
+
+
+Arguments
+
+- SHELL
The shell to generate the completion script for
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
+
+uv help
+Display documentation for a command
+Usage
+
+
+Arguments
+
+
+
+Options
+
+--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
+Can be provided multiple times.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
+May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.
+To view the location of the cache directory, run uv cache dir.
+May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
+By default, uv will automatically detect support for colors when writing to a terminal.
+Possible values:
+
+auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
+While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
+May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
+Relative paths are resolved with the given directory as the base.
+See --project to only change the project root directory.
+May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
+--managed-pythonRequire use of uv-managed Python versions.
+By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
+May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
+May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
+May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
+Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
+May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
+Instead, uv will search for a suitable Python version on the system.
+May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-pagerDisable pager when printing help
+--no-progressHide all progress outputs.
+For example, spinners or progress bars.
+May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
+--offlineDisable network access.
+When disabled, uv will only use locally cached data and locally available files.
+May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
+All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
+Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
+See --directory to change the working directory entirely.
+This setting has no effect when used in the uv pip interface.
+May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
+Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
+--verbose, -vUse verbose output.
+You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/environment/index.html b/site/uv-next/reference/environment/index.html
new file mode 100644
index 000000000..2b0ee751d
--- /dev/null
+++ b/site/uv-next/reference/environment/index.html
@@ -0,0 +1,8005 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Environment variables | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Environment variables
+uv defines and respects the following environment variables:
+UV_BREAK_SYSTEM_PACKAGES
+added in 0.1.32
+Equivalent to the --break-system-packages command-line argument. If set to true,
+uv will allow the installation of packages that conflict with system-installed packages.
+WARNING: UV_BREAK_SYSTEM_PACKAGES=true is intended for use in continuous integration
+(CI) or containerized environments and should be used with caution, as modifying the system
+Python can lead to unexpected behavior.
+UV_BUILD_CONSTRAINT
+added in 0.2.34
+Equivalent to the --build-constraints command-line argument. If set, uv will use this file
+as constraints for any source distribution builds. Uses space-separated list of files.
+UV_CACHE_DIR
+added in 0.0.5
+Equivalent to the --cache-dir command-line argument. If set, uv will use this
+directory for caching instead of the default cache directory.
+UV_COMPILE_BYTECODE
+added in 0.3.3
+Equivalent to the --compile-bytecode command-line argument. If set, uv
+will compile Python source files to bytecode after installation.
+UV_COMPILE_BYTECODE_TIMEOUT
+added in 0.7.22
+Timeout (in seconds) for bytecode compilation.
+UV_CONCURRENT_BUILDS
+added in 0.1.43
+Sets the maximum number of source distributions that uv will build
+concurrently at any given time.
+UV_CONCURRENT_DOWNLOADS
+added in 0.1.43
+Sets the maximum number of in-flight concurrent downloads that uv will
+perform at any given time.
+UV_CONCURRENT_INSTALLS
+added in 0.1.45
+Controls the number of threads used when installing and unzipping
+packages.
+UV_CONFIG_FILE
+added in 0.1.34
+Equivalent to the --config-file command-line argument. Expects a path to a
+local uv.toml file to use as the configuration file.
+UV_CONSTRAINT
+added in 0.1.36
+Equivalent to the --constraints command-line argument. If set, uv will use this
+file as the constraints file. Uses space-separated list of files.
+UV_CREDENTIALS_DIR
+added in 0.8.15
+The directory for storage of credentials when using a plain text backend.
+UV_CUSTOM_COMPILE_COMMAND
+added in 0.1.23
+Equivalent to the --custom-compile-command command-line argument.
+Used to override uv in the output header of the requirements.txt files generated by
+uv pip compile. Intended for use-cases in which uv pip compile is called from within a wrapper
+script, to include the name of the wrapper script in the output file.
+UV_DEFAULT_INDEX
+added in 0.4.23
+Equivalent to the --default-index command-line argument. If set, uv will use
+this URL as the default index when searching for packages.
+UV_DEV
+added in 0.8.7
+Equivalent to the --dev command-line argument. If set, uv will include
+development dependencies.
+UV_DOWNLOAD_URL
+added in 0.8.4
+The URL from which to download uv using the standalone installer. By default, installs from
+uv's GitHub Releases. INSTALLER_DOWNLOAD_URL is also supported as an alias, for backwards
+compatibility.
+UV_ENV_FILE
+added in 0.4.30
+.env files from which to load environment variables when executing uv run commands.
+UV_EXCLUDE
+added in 0.9.8
+Equivalent to the --excludes command-line argument. If set, uv will use this
+as the excludes file. Uses space-separated list of files.
+UV_EXCLUDE_NEWER
+added in 0.2.12
+Equivalent to the --exclude-newer command-line argument. If set, uv will
+exclude distributions published after the specified date.
+UV_EXTRA_INDEX_URL
+added in 0.1.3
+Equivalent to the --extra-index-url command-line argument. If set, uv will
+use this space-separated list of URLs as additional indexes when searching for packages.
+(Deprecated: use UV_INDEX instead.)
+UV_FIND_LINKS
+added in 0.4.19
+Equivalent to the --find-links command-line argument. If set, uv will use this
+comma-separated list of additional locations to search for packages.
+UV_FORK_STRATEGY
+added in 0.5.9
+Equivalent to the --fork-strategy argument. Controls version selection during universal
+resolution.
+UV_FROZEN
+added in 0.4.25
+Equivalent to the --frozen command-line argument. If set, uv will run without
+updating the uv.lock file.
+UV_GITHUB_TOKEN
+added in 0.4.10
+Equivalent to the --token argument for self update. A GitHub token for authentication.
+UV_GIT_LFS
+added in 0.5.19
+Enables fetching files stored in Git LFS when installing a package from a Git repository.
+UV_HTTP_RETRIES
+added in 0.7.21
+The number of retries for HTTP requests. (default: 3)
+UV_HTTP_TIMEOUT
+added in 0.1.7
+Timeout (in seconds) for HTTP requests. (default: 30 s)
+UV_INDEX
+added in 0.4.23
+Equivalent to the --index command-line argument. If set, uv will use this
+space-separated list of URLs as additional indexes when searching for packages.
+UV_INDEX_STRATEGY
+added in 0.1.29
+Equivalent to the --index-strategy command-line argument.
+For example, if set to unsafe-best-match, uv will consider versions of a given package
+available across all index URLs, rather than limiting its search to the first index URL
+that contains the package.
+UV_INDEX_URL
+added in 0.0.5
+Equivalent to the --index-url command-line argument. If set, uv will use this
+URL as the default index when searching for packages.
+(Deprecated: use UV_DEFAULT_INDEX instead.)
+UV_INDEX_{name}_PASSWORD
+added in 0.4.23
+Provides the HTTP Basic authentication password for a named index.
+The name parameter is the name of the index. For example, given an index named foo,
+the environment variable key would be UV_INDEX_FOO_PASSWORD.
+UV_INDEX_{name}_USERNAME
+added in 0.4.23
+Provides the HTTP Basic authentication username for a named index.
+The name parameter is the name of the index. For example, given an index named foo,
+the environment variable key would be UV_INDEX_FOO_USERNAME.
+UV_INIT_BUILD_BACKEND
+added in 0.8.2
+Equivalent to the --build-backend argument for uv init. Determines the default backend
+to use when creating a new project.
+UV_INSECURE_HOST
+added in 0.3.5
+Equivalent to the --allow-insecure-host argument.
+UV_INSECURE_NO_ZIP_VALIDATION
+added in 0.8.6
+Disable ZIP validation for streamed wheels and ZIP-based source distributions.
+WARNING: Disabling ZIP validation can expose your system to security risks by bypassing
+integrity checks and allowing uv to install potentially malicious ZIP files. If uv rejects
+a ZIP file due to failing validation, it is likely that the file is malformed; consider
+filing an issue with the package maintainer.
+UV_INSTALLER_GHE_BASE_URL
+added in 0.5.0
+The URL from which to download uv using the standalone installer and self update feature,
+in lieu of the default GitHub Enterprise URL.
+UV_INSTALLER_GITHUB_BASE_URL
+added in 0.5.0
+The URL from which to download uv using the standalone installer and self update feature,
+in lieu of the default GitHub URL.
+UV_INSTALL_DIR
+added in 0.5.0
+The directory in which to install uv using the standalone installer and self update feature.
+Defaults to ~/.local/bin.
+UV_ISOLATED
+added in 0.8.14
+Equivalent to the --isolated command-line argument. If set, uv will avoid discovering
+a pyproject.toml or uv.toml file.
+UV_KEYRING_PROVIDER
+added in 0.1.19
+Equivalent to the --keyring-provider command-line argument. If set, uv
+will use this value as the keyring provider.
+UV_LIBC
+added in 0.7.22
+Overrides the environment-determined libc on linux systems when filling in the current platform
+within Python version requests. Options are: gnu, gnueabi, gnueabihf, musl, and none.
+UV_LINK_MODE
+added in 0.1.40
+Equivalent to the --link-mode command-line argument. If set, uv will use this as
+a link mode.
+UV_LOCKED
+added in 0.4.25
+Equivalent to the --locked command-line argument. If set, uv will assert that the
+uv.lock remains unchanged.
+UV_LOG_CONTEXT
+added in 0.6.4
+Add additional context and structure to log messages.
+If logging is not enabled, e.g., with RUST_LOG or -v, this has no effect.
+UV_MANAGED_PYTHON
+added in 0.6.8
+Require use of uv-managed Python versions.
+UV_NATIVE_TLS
+added in 0.1.19
+Equivalent to the --native-tls command-line argument. If set to true, uv will
+use the system's trust store instead of the bundled webpki-roots crate.
+UV_NO_BINARY
+added in 0.5.30
+Equivalent to the --no-binary command-line argument. If set, uv will install
+all packages from source. The resolver will still use pre-built wheels to
+extract package metadata, if available.
+UV_NO_BINARY_PACKAGE
+added in 0.5.30
+Equivalent to the --no-binary-package command line argument. If set, uv will
+not use pre-built wheels for the given space-delimited list of packages.
+UV_NO_BUILD
+added in 0.1.40
+Equivalent to the --no-build command-line argument. If set, uv will not build
+source distributions.
+UV_NO_BUILD_ISOLATION
+added in 0.1.40
+Equivalent to the --no-build-isolation command-line argument. If set, uv will
+skip isolation when building source distributions.
+UV_NO_BUILD_PACKAGE
+added in 0.6.5
+Equivalent to the --no-build-package command line argument. If set, uv will
+not build source distributions for the given space-delimited list of packages.
+UV_NO_CACHE
+added in 0.1.2
+Equivalent to the --no-cache command-line argument. If set, uv will not use the
+cache for any operations.
+UV_NO_CONFIG
+added in 0.2.30
+Equivalent to the --no-config command-line argument. If set, uv will not read
+any configuration files from the current directory, parent directories, or user configuration
+directories.
+UV_NO_DEV
+added in 0.8.7
+Equivalent to the --no-dev command-line argument. If set, uv will exclude
+development dependencies.
+UV_NO_EDITABLE
+added in 0.6.15
+Equivalent to the --no-editable command-line argument. If set, uv
+installs or exports any editable dependencies, including the project and any workspace
+members, as non-editable.
+UV_NO_ENV_FILE
+added in 0.4.30
+Ignore .env files when executing uv run commands.
+UV_NO_GITHUB_FAST_PATH
+added in 0.7.13
+Disable GitHub-specific requests that allow uv to skip git fetch in some circumstances.
+UV_NO_GROUP
+added in 0.9.8
+Equivalent to the --no-group command-line argument. If set, uv will disable
+the specified dependency groups for the given space-delimited list of packages.
+UV_NO_HF_TOKEN
+added in 0.8.1
+Disable Hugging Face authentication, even if HF_TOKEN is set.
+UV_NO_INSTALLER_METADATA
+added in 0.5.7
+Skip writing uv installer metadata files (e.g., INSTALLER, REQUESTED, and direct_url.json) to site-packages .dist-info directories.
+UV_NO_MANAGED_PYTHON
+added in 0.6.8
+Disable use of uv-managed Python versions.
+UV_NO_MODIFY_PATH
+added in 0.8.4
+Avoid modifying the PATH environment variable when installing uv using the standalone
+installer and self update feature. INSTALLER_NO_MODIFY_PATH is also supported as an
+alias, for backwards compatibility.
+UV_NO_PROGRESS
+added in 0.2.28
+Equivalent to the --no-progress command-line argument. Disables all progress output. For
+example, spinners and progress bars.
+UV_NO_SOURCES
+added in 0.9.8
+Equivalent to the --no-sources command-line argument. If set, uv will ignore
+[tool.uv.sources] annotations when resolving dependencies.
+UV_NO_SYNC
+added in 0.4.18
+Equivalent to the --no-sync command-line argument. If set, uv will skip updating
+the environment.
+UV_NO_VERIFY_HASHES
+added in 0.5.3
+Equivalent to the --no-verify-hashes argument. Disables hash verification for
+requirements.txt files.
+UV_NO_WRAP
+added in 0.0.5
+Use to disable line wrapping for diagnostics.
+UV_OFFLINE
+added in 0.5.9
+Equivalent to the --offline command-line argument. If set, uv will disable network access.
+UV_OVERRIDE
+added in 0.2.22
+Equivalent to the --overrides command-line argument. If set, uv will use this file
+as the overrides file. Uses space-separated list of files.
+UV_PRERELEASE
+added in 0.1.16
+Equivalent to the --prerelease command-line argument. For example, if set to
+allow, uv will allow pre-release versions for all dependencies.
+UV_PREVIEW
+added in 0.1.37
+Equivalent to the --preview argument. Enables preview mode.
+UV_PREVIEW_FEATURES
+added in 0.8.4
+Equivalent to the --preview-features argument. Enables specific preview features.
+UV_PROJECT
+added in 0.4.4
+Equivalent to the --project command-line argument.
+UV_PROJECT_ENVIRONMENT
+added in 0.4.4
+Specifies the path to the directory to use for a project virtual environment.
+See the project documentation
+for more details.
+UV_PUBLISH_CHECK_URL
+added in 0.4.30
+Don't upload a file if it already exists on the index. The value is the URL of the index.
+UV_PUBLISH_INDEX
+added in 0.5.8
+Equivalent to the --index command-line argument in uv publish. If
+set, uv the index with this name in the configuration for publishing.
+UV_PUBLISH_PASSWORD
+added in 0.4.16
+Equivalent to the --password command-line argument in uv publish. If
+set, uv will use this password for publishing.
+UV_PUBLISH_TOKEN
+added in 0.4.16
+Equivalent to the --token command-line argument in uv publish. If set, uv
+will use this token (with the username __token__) for publishing.
+UV_PUBLISH_URL
+added in 0.4.16
+Equivalent to the --publish-url command-line argument. The URL of the upload
+endpoint of the index to use with uv publish.
+UV_PUBLISH_USERNAME
+added in 0.4.16
+Equivalent to the --username command-line argument in uv publish. If
+set, uv will use this username for publishing.
+UV_PYPY_INSTALL_MIRROR
+added in 0.2.35
+Managed PyPy installations are downloaded from python.org.
+This variable can be set to a mirror URL to use a
+different source for PyPy installations. The provided URL will replace
+https://downloads.python.org/pypy in, e.g.,
+https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2.
+Distributions can be read from a local directory by using the file:// URL scheme.
+UV_PYTHON
+added in 0.1.40
+Equivalent to the --python command-line argument. If set to a path, uv will use
+this Python interpreter for all operations.
+UV_PYTHON_BIN_DIR
+added in 0.4.29
+Specifies the directory to place links to installed, managed Python executables.
+UV_PYTHON_CACHE_DIR
+added in 0.7.0
+Specifies the directory for caching the archives of managed Python installations before
+installation.
+UV_PYTHON_CPYTHON_BUILD
+added in 0.8.14
+Pin managed CPython versions to a specific build version.
+For CPython, this should be the build date (e.g., "20250814").
+UV_PYTHON_DOWNLOADS
+added in 0.3.2
+Equivalent to the
+python-downloads setting and, when disabled, the
+--no-python-downloads option. Whether uv should allow Python downloads.
+UV_PYTHON_DOWNLOADS_JSON_URL
+added in 0.6.13
+Managed Python installations information is hardcoded in the uv binary.
+This variable can be set to a URL pointing to JSON to use as a list for Python installations.
+This will allow for setting each property of the Python installation, mostly the url part for offline mirror.
+Note that currently, only local paths are supported.
+UV_PYTHON_GRAALPY_BUILD
+added in 0.8.14
+Pin managed GraalPy versions to a specific build version.
+For GraalPy, this should be the GraalPy version (e.g., "24.2.2").
+UV_PYTHON_INSTALL_BIN
+added in 0.8.0
+Whether to install the Python executable into the UV_PYTHON_BIN_DIR directory.
+UV_PYTHON_INSTALL_DIR
+added in 0.2.22
+Specifies the directory for storing managed Python installations.
+UV_PYTHON_INSTALL_MIRROR
+added in 0.2.35
+Managed Python installations are downloaded from the Astral
+python-build-standalone project.
+This variable can be set to a mirror URL to use a different source for Python installations.
+The provided URL will replace https://github.com/astral-sh/python-build-standalone/releases/download in, e.g.,
+https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz.
+Distributions can be read from a local directory by using the file:// URL scheme.
+UV_PYTHON_INSTALL_REGISTRY
+added in 0.8.0
+Whether to install the Python executable into the Windows registry.
+UV_PYTHON_PREFERENCE
+added in 0.3.2
+Whether uv should prefer system or managed Python versions.
+UV_PYTHON_PYODIDE_BUILD
+added in 0.8.14
+Pin managed Pyodide versions to a specific build version.
+For Pyodide, this should be the Pyodide version (e.g., "0.28.1").
+UV_PYTHON_PYPY_BUILD
+added in 0.8.14
+Pin managed PyPy versions to a specific build version.
+For PyPy, this should be the PyPy version (e.g., "7.3.20").
+UV_REQUEST_TIMEOUT
+added in 0.1.6
+Timeout (in seconds) for HTTP requests. Equivalent to UV_HTTP_TIMEOUT.
+UV_REQUIRE_HASHES
+added in 0.1.34
+Equivalent to the --require-hashes command-line argument. If set to true,
+uv will require that all dependencies have a hash specified in the requirements file.
+UV_RESOLUTION
+added in 0.1.27
+Equivalent to the --resolution command-line argument. For example, if set to
+lowest-direct, uv will install the lowest compatible versions of all direct dependencies.
+UV_S3_ENDPOINT_URL
+added in 0.8.21
+The URL to treat as an S3-compatible storage endpoint. Requests to this endpoint
+will be signed using AWS Signature Version 4 based on the AWS_ACCESS_KEY_ID,
+AWS_SECRET_ACCESS_KEY, AWS_PROFILE, and AWS_CONFIG_FILE environment variables.
+UV_SKIP_WHEEL_FILENAME_CHECK
+added in 0.8.23
+Avoid verifying that wheel filenames match their contents when installing wheels. This
+is not recommended, as wheels with inconsistent filenames should be considered invalid and
+corrected by the relevant package maintainers; however, this option can be used to work
+around invalid artifacts in rare cases.
+UV_STACK_SIZE
+added in 0.0.5
+Use to set the stack size used by uv.
+The value is in bytes, and if both UV_STACK_SIZE are RUST_MIN_STACK unset, uv uses a 4MB
+(4194304) stack. UV_STACK_SIZE takes precedence over RUST_MIN_STACK.
+Unlike the normal RUST_MIN_STACK semantics, this can affect main thread
+stack size, because we actually spawn our own main2 thread to work around
+the fact that Windows' real main thread is only 1MB. That thread has size
+max(UV_STACK_SIZE, 1MB).
+UV_SYSTEM_PYTHON
+added in 0.1.18
+Equivalent to the --system command-line argument. If set to true, uv will
+use the first Python interpreter found in the system PATH.
+WARNING: UV_SYSTEM_PYTHON=true is intended for use in continuous integration (CI)
+or containerized environments and should be used with caution, as modifying the system
+Python can lead to unexpected behavior.
+UV_TEST_NO_HTTP_RETRY_DELAY
+added in 0.7.21
+Used to disable delay for HTTP retries in tests.
+UV_TOOL_BIN_DIR
+added in 0.3.0
+Specifies the "bin" directory for installing tool executables.
+UV_TOOL_DIR
+added in 0.2.16
+Specifies the directory where uv stores managed tools.
+UV_TORCH_BACKEND
+added in 0.6.9
+Equivalent to the --torch-backend command-line argument (e.g., cpu, cu126, or auto).
+UV_UNMANAGED_INSTALL
+added in 0.5.0
+Used ephemeral environments like CI to install uv to a specific path while preventing
+the installer from modifying shell profiles or environment variables.
+UV_UPLOAD_HTTP_TIMEOUT
+added in 0.9.1
+Timeout (in seconds) for only upload HTTP requests. (default: 900 s)
+UV_VENV_CLEAR
+added in 0.8.0
+Equivalent to the --clear command-line argument. If set, uv will remove any
+existing files or directories at the target path.
+UV_VENV_SEED
+added in 0.5.21
+Install seed packages (one or more of: pip, setuptools, and wheel) into the virtual environment
+created by uv venv.
+Note that setuptools and wheel are not included in Python 3.12+ environments.
+UV_WORKING_DIRECTORY
+added in 0.9.1
+Equivalent to the --directory command-line argument.
+Externally defined variables
+uv also reads the following externally defined environment variables:
+ALL_PROXY
+added in 0.1.38
+General proxy for all network requests.
+ANDROID_API_LEVEL
+added in 0.8.16
+Used with --python-platform aarch64-linux-android and related variants to set the
+Android API level. (i.e., the minimum supported Android API level).
+Defaults to 24.
+APPDATA
+added in 0.1.42
+Path to user-level configuration directory on Windows systems.
+AWS_ACCESS_KEY_ID
+added in 0.8.21
+The AWS access key ID to use when signing S3 requests.
+AWS_CONFIG_FILE
+added in 0.8.21
+The AWS config file to use when signing S3 requests.
+AWS_DEFAULT_REGION
+added in 0.8.21
+The default AWS region to use when signing S3 requests, if AWS_REGION is not set.
+AWS_PROFILE
+added in 0.8.21
+The AWS profile to use when signing S3 requests.
+AWS_REGION
+added in 0.8.21
+The AWS region to use when signing S3 requests.
+AWS_SECRET_ACCESS_KEY
+added in 0.8.21
+The AWS secret access key to use when signing S3 requests.
+AWS_SESSION_TOKEN
+added in 0.8.21
+The AWS session token to use when signing S3 requests.
+AWS_SHARED_CREDENTIALS_FILE
+added in 0.8.21
+The AWS shared credentials file to use when signing S3 requests.
+BASH_VERSION
+added in 0.1.28
+Used to detect Bash shell usage.
+CLICOLOR_FORCE
+added in 0.1.32
+Use to control color via anstyle.
+COLUMNS
+added in 0.6.2
+Overrides terminal width used for wrapping. This variable is not read by uv directly.
+This is a quasi-standard variable, described, e.g., in ncurses(3x).
+CONDA_DEFAULT_ENV
+added in 0.5.0
+Used to determine the name of the active Conda environment.
+CONDA_PREFIX
+added in 0.0.5
+Used to detect the path of an active Conda environment.
+FISH_VERSION
+added in 0.1.28
+Used to detect Fish shell usage.
+FORCE_COLOR
+added in 0.2.7
+Forces colored output regardless of terminal support.
+See force-color.org.
+GITHUB_ACTIONS
+added in 0.4.16
+Indicates that the current process is running in GitHub Actions.
+uv publish may attempt trusted publishing flows when set
+to true.
+GITLAB_CI
+added in 0.8.18
+Indicates that the current process is running in GitLab CI.
+uv publish may attempt trusted publishing flows when set
+to true.
+HF_TOKEN
+added in 0.8.1
+Authentication token for Hugging Face requests. When set, uv will use this token
+when making requests to https://huggingface.co/ and any subdomains.
+HOME
+added in 0.0.5
+The standard HOME env var.
+HTTPS_PROXY
+added in 0.1.38
+Proxy for HTTPS requests.
+HTTP_PROXY
+added in 0.1.38
+Proxy for HTTP requests.
+HTTP_TIMEOUT
+added in 0.1.7
+Timeout (in seconds) for HTTP requests. Equivalent to UV_HTTP_TIMEOUT.
+IPHONEOS_DEPLOYMENT_TARGET
+added in 0.8.16
+Used with --python-platform arm64-apple-ios and related variants to set the
+deployment target (i.e., the minimum supported iOS version).
+Defaults to 13.0.
+JPY_SESSION_NAME
+added in 0.2.6
+Used to detect when running inside a Jupyter notebook.
+KSH_VERSION
+added in 0.2.33
+Used to detect Ksh shell usage.
+LOCALAPPDATA
+added in 0.3.3
+Used to look for Microsoft Store Pythons installations.
+MACOSX_DEPLOYMENT_TARGET
+added in 0.1.42
+Used with --python-platform macos and related variants to set the
+deployment target (i.e., the minimum supported macOS version).
+Defaults to 13.0, the least-recent non-EOL macOS version at time of writing.
+NETRC
+added in 0.1.16
+Use to set the .netrc file location.
+NO_COLOR
+added in 0.2.7
+Disables colored output (takes precedence over FORCE_COLOR).
+See no-color.org.
+NO_PROXY
+added in 0.1.38
+Comma-separated list of hostnames (e.g., example.com) and/or patterns (e.g., 192.168.1.0/24) that should bypass the proxy.
+NU_VERSION
+added in 0.1.16
+Used to detect NuShell usage.
+PAGER
+added in 0.4.18
+The standard PAGER posix env var. Used by uv to configure the appropriate pager.
+PATH
+added in 0.0.5
+The standard PATH env var.
+PROMPT
+added in 0.1.16
+Used to detect the use of the Windows Command Prompt (as opposed to PowerShell).
+PWD
+added in 0.0.5
+The standard PWD posix env var.
+PYC_INVALIDATION_MODE
+added in 0.1.7
+The validation modes to use when run with --compile.
+See PycInvalidationMode.
+PYTHONPATH
+added in 0.1.22
+Adds directories to Python module search path (e.g., PYTHONPATH=/path/to/modules).
+PYX_API_KEY
+added in 0.8.15
+The pyx API key (e.g., sk-pyx-...).
+PYX_API_URL
+added in 0.8.15
+The URL of the pyx Simple API server.
+PYX_AUTH_TOKEN
+added in 0.8.15
+The pyx authentication token (e.g., eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...), as output by uv auth token.
+PYX_CDN_DOMAIN
+added in 0.8.15
+The domain of the pyx CDN.
+PYX_CREDENTIALS_DIR
+added in 0.8.15
+Specifies the directory where uv stores pyx credentials.
+RUST_BACKTRACE
+added in 0.7.22
+If set, it can be used to display more stack trace details when a panic occurs.
+This is used by uv particularly on windows to show more details during a platform exception.
+For example:
+
+RUST_BACKTRACE=1 will print a short backtrace.RUST_BACKTRACE=full will print a full backtrace.
+See the Rust backtrace documentation
+for more.
+RUST_LOG
+added in 0.0.5
+If set, uv will use this value as the log level for its --verbose output. Accepts
+any filter compatible with the tracing_subscriber crate.
+For example:
+
+RUST_LOG=uv=debug is the equivalent of adding --verbose to the command lineRUST_LOG=trace will enable trace-level logging.
+See the tracing documentation
+for more.
+RUST_MIN_STACK
+added in 0.5.19
+Use to set the stack size used by uv.
+The value is in bytes, and if both UV_STACK_SIZE are RUST_MIN_STACK unset, uv uses a 4MB
+(4194304) stack. UV_STACK_SIZE takes precedence over RUST_MIN_STACK.
+Prefer setting UV_STACK_SIZE, since RUST_MIN_STACK also affects subprocesses, such as
+build backends that use Rust code.
+Unlike the normal RUST_MIN_STACK semantics, this can affect main thread
+stack size, because we actually spawn our own main2 thread to work around
+the fact that Windows' real main thread is only 1MB. That thread has size
+max(RUST_MIN_STACK, 1MB).
+SHELL
+added in 0.1.16
+The standard SHELL posix env var.
+SSL_CERT_FILE
+added in 0.1.14
+Custom certificate bundle file path for SSL connections.
+SSL_CLIENT_CERT
+added in 0.2.11
+If set, uv will use this file for mTLS authentication.
+This should be a single file containing both the certificate and the private key in PEM format.
+SYSTEMDRIVE
+added in 0.4.26
+Path to system-level configuration directory on Windows systems.
+TRACING_DURATIONS_FILE
+added in 0.0.5
+Use to create the tracing durations file via the tracing-durations-export feature.
+USERPROFILE
+added in 0.0.5
+Path to root directory of user's profile on Windows systems.
+UV
+added in 0.6.0
+The path to the binary that was used to invoke uv.
+This is propagated to all subprocesses spawned by uv.
+If the executable was invoked through a symbolic link, some platforms will return the path
+of the symbolic link and other platforms will return the path of the symbolic link’s target.
+See https://doc.rust-lang.org/std/env/fn.current_exe.html#security for security
+considerations.
+VIRTUAL_ENV
+added in 0.0.5
+Used to detect an activated virtual environment.
+VIRTUAL_ENV_DISABLE_PROMPT
+added in 0.0.5
+If set to 1 before a virtual environment is activated, then the
+virtual environment name will not be prepended to the terminal prompt.
+XDG_BIN_HOME
+added in 0.2.16
+Path to directory where executables are installed.
+XDG_CACHE_HOME
+added in 0.1.17
+Path to cache directory on Unix systems.
+XDG_CONFIG_DIRS
+added in 0.4.26
+Path to system-level configuration directory on Unix systems.
+XDG_CONFIG_HOME
+added in 0.1.34
+Path to user-level configuration directory on Unix systems.
+XDG_DATA_HOME
+added in 0.2.16
+Path to directory for storing managed Python installations and tools.
+ZDOTDIR
+added in 0.2.25
+Used to determine which .zshenv to use when Zsh is being used.
+ZSH_VERSION
+added in 0.1.28
+Used to detect Zsh shell usage.
+_CONDA_ROOT
+added in 0.8.18
+Used to determine the root install path of Conda.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/index.html b/site/uv-next/reference/index.html
new file mode 100644
index 000000000..c79154a10
--- /dev/null
+++ b/site/uv-next/reference/index.html
@@ -0,0 +1,3378 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Reference | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Reference
+The reference section provides information about specific parts of uv:
+
+- Commands: A reference for uv's command line interface.
+- Settings: A reference for uv's configuration schema.
+- Resolver: Details about the internals of uv's resolver.
+- Policies: uv's versioning policy, platform support policy, and license.
+
+Looking for a broader overview? Check out the concepts documentation.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/installer/index.html b/site/uv-next/reference/installer/index.html
new file mode 100644
index 000000000..97a4d3474
--- /dev/null
+++ b/site/uv-next/reference/installer/index.html
@@ -0,0 +1,3550 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+The uv installer | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+The uv installer
+Changing the installation path
+By default, uv is installed to ~/.local/bin. If XDG_BIN_HOME is set, it will be used instead.
+Similarly, if XDG_DATA_HOME is set, the target directory will be inferred as
+XDG_DATA_HOME/../bin.
+To change the installation path, use UV_INSTALL_DIR:
+
+
+
+Disabling shell modifications
+The installer may also update your shell profiles to ensure the uv binary is on your PATH. To
+disable this behavior, use UV_NO_MODIFY_PATH. For example:
+
+If installed with UV_NO_MODIFY_PATH, subsequent operations, like uv self update, will not modify
+your shell profiles.
+Unmanaged installations
+In ephemeral environments like CI, use UV_UNMANAGED_INSTALL to install uv to a specific path while
+preventing the installer from modifying shell profiles or environment variables:
+
+The use of UV_UNMANAGED_INSTALL will also disable self-updates (via uv self update).
+Passing options to the installation script
+Using environment variables is recommended because they are consistent across platforms. However,
+options can be passed directly to the installation script. For example, to see the available
+options:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/internals/index.html b/site/uv-next/reference/internals/index.html
new file mode 100644
index 000000000..bdba64c7a
--- /dev/null
+++ b/site/uv-next/reference/internals/index.html
@@ -0,0 +1,3394 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Internals | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/internals/resolver/index.html b/site/uv-next/reference/internals/resolver/index.html
new file mode 100644
index 000000000..2eecb1c9c
--- /dev/null
+++ b/site/uv-next/reference/internals/resolver/index.html
@@ -0,0 +1,3906 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Resolver internals | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Resolver internals
+
+Tip
+This document focuses on the internal workings of uv's resolver. For using uv, see the
+resolution concept documentation.
+
+Resolver
+As defined in a textbook, resolution, or finding a set of version to install from a given set of
+requirements, is equivalent to the
+SAT problem and thereby NP-complete:
+in the worst case you have to try all possible combinations of all versions of all packages and
+there are no general, fast algorithms. In practice, this is misleading for a number of reasons:
+
+- The slowest part of resolution in uv is loading package and version metadata, even if it's cached.
+- There are many possible solutions, but some are preferable to others. For example, we generally
+ prefer using the latest version of packages.
+- Package dependencies are complex, e.g., there are contiguous versions ranges — not arbitrary
+ boolean inclusion/exclusions of versions, adjacent releases often have the same or similar
+ requirements, etc.
+- For most resolutions, the resolver doesn't need to backtrack, picking versions iteratively is
+ sufficient. If there are version preferences from a previous resolution, barely any work needs to
+ be done.
+- When resolution fails, more information is needed than a message that there is no solution (as is
+ seen in SAT solvers). Instead, the resolver should produce an understandable error trace that
+ states which packages are involved in away to allows a user to remove the conflict.
+- The most important heuristic for performance and user experience is determining the order in which
+ decisions are made through prioritization.
+
+uv uses pubgrub-rs, the Rust implementation of
+PubGrub, an incremental version solver. PubGrub in uv
+works in the following steps:
+
+- Start with a partial solution that declares which packages versions have been selected and which
+ are undecided. Initially, only a virtual root package is decided.
+- The highest priority package is selected from the undecided packages. Roughly, packages with URLs
+ (including file, git, etc.) have the highest priority, then those with more exact specifiers (such
+ as
==), then those with less strict specifiers. Inside each category, packages are ordered by
+ when they were first seen (i.e. order in a file), making the resolution deterministic.
+- A version is picked for the selected package. The version must works with all specifiers from the
+ requirements in the partial solution and must not be previously marked as incompatible. The
+ resolver prefers versions from a lockfile (
uv.lock or -o requirements.txt) and those installed
+ in the current environment. Versions are checked from highest to lowest (unless using an
+ alternative resolution strategy).
+- All requirements of the selected package version are added to the undecided packages. uv
+ prefetches their metadata in the background to improve performance.
+- The process is either repeated with the next package unless a conflict is detected, in which the
+ resolver will backtrack. For example, the partial solution contains, among other packages,
a 2
+ then b 2 with the requirements a 2 -> c 1 and b 2 -> c 2. No compatible version of c can
+ be found. PubGrub can determine this was caused by a 2 and b 2 and add the incompatibility
+ {a 2, b 2}, meaning that when either is picked, the other cannot be selected. The partial
+ solution is restored to a 2 with the tracked incompatibility and the resolver attempts to pick a
+ new version for b.
+
+Eventually, the resolver either picks compatible versions for all packages (a successful resolution)
+or there is an incompatibility including the virtual "root" package which defines the versions
+requested by the user. An incompatibility with the root package indicates that whatever versions of
+the root dependencies and their transitive dependencies are picked, there will always be a conflict.
+From the incompatibilities tracked in PubGrub, an error message is constructed to enumerate the
+involved packages.
+
+Tip
+For more details on the PubGrub algorithm, see Internals of the PubGrub
+algorithm.
+
+In addition to PubGrub's base algorithm, we also use a heuristic that backtracks and switches the
+order of two packages if they have been conflicting too much.
+Forking
+Python resolvers historically didn't support backtracking, and even with backtracking, resolution
+was usually limited to single environment, which one specific architecture, operating system, Python
+version, and Python implementation. Some packages use contradictory requirements for different
+environments, for example:
+
+Since Python only allows one version of each package, a naive resolver would error here. Inspired by
+Poetry, uv uses a forking resolver: whenever there are
+multiple requirements for a package with different markers, the resolution is split.
+In the above example, the partial solution would be split into two resolutions, one for
+python_version >= "3.11" and one for python_version < "3.11".
+If markers overlap or are missing a part of the marker space, the resolver splits additional times —
+there can be many forks per package. For example, given:
+
+A fork would be created for sys_platform == 'darwin', for sys_platform == 'win32', and for
+sys_platform != 'darwin' and sys_platform != 'win32'.
+Forks can be nested, e.g., each fork is dependent on any previous forks that occurred. Forks with
+identical packages are merged to keep the number of forks low.
+
+Tip
+Forking can be observed in the logs of uv lock -v by looking for
+Splitting resolution on ..., Solving split ... (requires-python: ...) and Split ... resolution
+took ....
+
+One difficulty in a forking resolver is that where splits occur is dependent on the order packages
+are seen, which is in turn dependent on the preferences, e.g., from uv.lock. So it is possible for
+the resolver to solve the requirements with specific forks, write this to the lockfile, and when the
+resolver is invoked again, a different solution is found because the preferences result in different
+fork points. To avoid this, the resolution-markers of each fork and each package that diverges
+between forks is written to the lockfile. When performing a new resolution, the forks from the
+lockfile are used to ensure the resolution is stable. When requirements change, new forks may be
+added to the saved forks.
+Wheel tags
+While uv's resolution is universal with respect to environment markers, this doesn't extend to wheel
+tags. Wheel tags can encode the Python version, Python implementation, operating system, and
+architecture. For example, torch-2.4.0-cp312-cp312-manylinux2014_aarch64.whl is only compatible
+with CPython 3.12 on arm64 Linux with glibc>=2.17 (per the manylinux2014 policy), while
+tqdm-4.66.4-py3-none-any.whl works with all Python 3 versions and interpreters on any operating
+system and architecture. Most projects have a universally compatible source distribution that can be
+used when attempted to install a package that has no compatible wheel, but some packages, such as
+torch, don't publish a source distribution. In this case an installation on, e.g., Python 3.13, an
+uncommon operating system, or architecture, will fail and complain that there is no matching wheel.
+Marker and wheel tag filtering
+In every fork, we know what markers are possible. In non-universal resolution, we know their exact
+values. In universal mode, we know at least a constraint for the python requirement, e.g.,
+requires-python = ">=3.12" means that importlib_metadata; python_version < "3.10" can be
+discarded because it can never be installed. If additionally tool.uv.environments is set, we can
+filter out requirements with markers disjoint with those environments. Inside each fork, we can
+additionally filter by the fork markers.
+There is some redundancy in the marker expressions, where the value of one marker field implies the
+value of another field. Internally, we normalize python_version and python_full_version as well
+as known values of platform_system and sys_platform to a shared canonical representation, so
+they can match against each other.
+When we selected a version with a local tag (e.g.,1.2.3+localtag) and the wheels don't cover
+support for Windows, Linux and macOS, and there is a base version without tag (e.g.,1.2.3) with
+support for a missing platform, we fork trying to extend the platform support by using both the
+version with local tag and without local tag depending on the platform. This helps with packages
+that use the local tag for different hardware accelerators such as torch. While there is no 1:1
+mapping between wheel tags and markers, we can do a mapping for well-known platforms, including
+Windows, Linux and macOS.
+Metadata consistency
+uv, similar to poetry, requires that wheels of a single version of a package in a specific index
+have the same dependencies (Requires-Dist in METADATA), including wheels build from a source
+distribution. More generally, uv assumes that each wheel has the same METADATA file in its
+dist-info directory.
+numpy 2.3.2 for example has 73 wheels. Without this assumption, uv would have to make 73 network
+requests to fetch its metadata, instead of a single one. Another problem we would have without
+metadata consistency is the lack of a 1:1 mapping between markers and wheel tags. Wheel tags can
+include the glibc version while the PEP 508 markers cannot represent it. If wheels had different
+metadata, a universal resolver would have to track two dimensions simultaneously, PEP 508 markers
+and wheel tags. This would increase complexity a lot, and the correspondence between the two is not
+properly specified. PEP 508 markers have been introduced specifically to allow different
+dependencies between different platform, i.e. to have a single dependency declaration for all
+wheels, such as project.[optional-]dependencies. If the markers are not sufficient, we should
+extend PEP 508 markers instead of using a parallel system of wheel tags.
+Another aspect of metadata consistency is that a source distribution must build into a wheel with
+the same metadata as the wheels, or if there are no wheels, into the same metadata each time. If
+this assumption is violated, sound dependency locking becomes impossible: Consider a package A has a
+source distribution. During resolution, we build A v1 and obtain the dependencies B>=2,<3. We lock
+A==1 and B==2. When installing the lockfile on the target machine, we build again and obtain
+dependencies B>=3,<4 and C>=1,<2. The lockfile fails to install: Due to the changed constraints,
+the locked version of B is incompatible, and there's no locked candidate for C. Re-resolving
+after this would both be a reproducibility problem (the lockfile is effectively ignored) and a
+security concern (C has not been reviewed, neither was B==3). It's possible to fail on
+installation if that happens, but a late error, possibly during deployment, is a bad user
+experience. There is already a case where uv fails on installation, packages with no source
+distribution and only platform specific wheels incompatible with the current platform. While uv has
+required environments as
+mitigation, this requires a not well known configuration option, and questions around (un)supported
+environments are one of the most common problem for uv users. A similar situation with source
+distributions should be avoided.
+While older versions of torch and tensorflow had inconsistent metadata, all recent versions have
+consistent metadata, and we are not aware of any major package with inconsistent metadata. There is
+however no requirement in the Python packaging standards that metadata must be consistent, and
+requests to enforce this in the standards have been rejected
+(https://discuss.python.org/t/enforcing-consistent-metadata-for-packages/50008).
+There are packages that have native code that links against the native code in another package, such
+as torch. These package may support building against a range of torch versions, but once built, they
+are constrained to a specific torch version, and the runtime torch version must match the build-time
+version. These are currently a pain point across all package managers, as all major package managers
+from pip to uv cache source distribution builds. uv supports multiple builds depending on the
+version of the already installed package using
+ tool.uv.extra-build-dependencies
+with match-runtime = true. This is a workaround that needs to be made on the user side for each
+affected package, instead of library developers declaring this requirement, which would be possible
+with native standards support.
+Requires-python
+To ensure that a resolution with requires-python = ">=3.9" can actually be installed for the
+included Python versions, uv requires that all dependencies have the same minimum Python version.
+Package versions that declare a higher minimum Python version, e.g., requires-python = ">=3.10",
+are rejected, because a resolution with that version can't be installed on Python 3.9. This ensures
+that when you are on an old Python version, you can install old packages, instead of getting newer
+packages that require newer Python syntax or standard library features.
+uv ignores upper-bounds on requires-python, with special handling for packages with only
+ABI-specific wheels. For example, if a package declares requires-python = ">=3.8,<4", the <4
+part is ignored. There is a detailed discussion with drawbacks and alternatives in
+#4022 and this
+DPO thread, this section
+summarizes the aspects most relevant to uv's design.
+For most projects, it's not possible to determine whether they will be compatible with a new version
+before it's released, so blocking newer versions in advance would block users from upgrading or
+testing newer Python versions. The exceptions are packages which use the unstable C ABI or internals
+of CPython such as its bytecode format.
+Introducing a requires-python upper bound to a project that previously wasn't using one will not
+prevent the project from being used on a too recent Python version. Instead of failing, the resolver
+will pick an older version without the bound, circumventing the bound.
+For the resolution to be as universally installable as possible, uv ensures that the selected
+dependency versions are compatible with the requires-python range of the project. For example, for
+a project with requires-python = ">=3.12", uv will not use a dependency version with
+requires-python = ">=3.13", as otherwise the resolution is not installable on Python 3.12, which
+the project declares to support. Applying the same logic to upper bounds means that bumping the
+upper Python version bound on a project makes it compatible with less dependency versions,
+potentially failing to resolve when no version of a dependency supports the required range. (Bumping
+the lower Python version bound has the inverse effect, it only increases the set of supported
+dependency versions.)
+Note that this is different for Conda, as the Conda solver also determines the Python version, so it
+can choose a lower Python version instead. Conda can also change metadata after a release, so it can
+update compatibility for a new Python version, while metadata on PyPI cannot be changed once
+published.
+Ignoring an upper bound is a problem for packages such as numpy which use the version-dependent C
+API of CPython. As of writing, each numpy release support 4 Python minor versions, e.g., numpy 2.0.0
+has wheels for CPython 3.9 through 3.12 and declares requires-python = ">=3.9", while numpy 2.1.0
+has wheels for CPython 3.10 through 3.13 and declares requires-python = ">=3.10". This means that
+when uv resolves a numpy>=2,<3 requirement in a project with requires-python = ">=3.9", it
+selects numpy 2.0.0 and the lockfile doesn't install on Python 3.13 or newer. To alleviate this,
+whenever uv rejects a version that requires a newer Python version, we fork by splitting the
+resolution markers on that Python version. This behavior can be controlled by --fork-strategy. In
+the example case, upon encountering numpy 2.1.0 we fork into Python versions >=3.9,<3.10 and
+>=3.10 and resolve two different numpy versions:
+numpy==2.0.0; python_version >= "3.9" and python_version < "3.10"
+numpy==2.1.0; python_version >= "3.10"
+
+There's one case where uv does consider the upper bound: When the project uses an upper bound on
+requires Python, such as requires-python = "==3.13.*" for an application that only deploys to
+Python 3.13. uv prunes wheels from the lockfile that are outside the range (e.g., cp312 and
+cp314) in a post-processing step, which does not influence the resolution itself.
+URL dependencies
+In uv, a dependency can either be a registry dependency, a package with a version specifier or the
+plain package name, or a URL dependency. All requirements in the form {name} @ {url} are URL
+dependencies, and also all dependencies that have a git,url, path, or workspace source.
+When a URL is declared for a package, uv pins the package to this URL, and the version this URL
+implies. If there are two conflicting URLs for a package, the resolver errors, as a URL can only be
+declared as something akin to an exact == pin, and not as list of URLs. A list of URLs is
+supported through flat indexes instead.
+uv requires that URLs are either declared directly (in the project, in a
+workspace member, in a
+constraint, or in an
+override, any location that is discovered
+directly), or by other URL dependencies. uv discovers all URL dependencies and their transitive URL
+dependencies ahead of the resolution and pins all packages to the URLs and the versions they imply.
+uv does not allow URLs in index packages. This has two reasons: One is a security and predictability
+aspect, that forbids registry distributions to point to non-registry distributions and helps
+auditing which URLs can be accessed. For example, when only using one index URL and no URL
+dependencies, uv will not install any package from outside the index.
+The other is that URLs can add additional versions to the resolution. Say the root package depends
+on foo, bar, and baz, all registry dependencies. foo depends on bar >= 2, but bar only has version
+1 on the index. With the incremental approach, this is an error: foo cannot be fulfilled, there is a
+resolver error. If URLs on index packages were allowed, it could be that there is a version of baz
+declares a dependency on baz-core and that has a version that declares
+bar @ https://example.com/bar-2-py3-none-any.whl adding a version of bar that makes requirements
+resolve. If a dependency can add new versions, discarding any version in the resolver would require
+looking at all possible versions of all direct and transitive dependencies. This breaks the core
+assumption incremental resolvers make that the set of versions for a package is static and would
+require to always fetch the metadata for all possibly reachable version.
+Prioritization
+Prioritization is important for both performance and for better resolutions.
+If we try many versions we have to later discard, resolution is slow, both because we have to read
+metadata we didn't need and because we have to track a lot of (conflict) information for this
+discarded subtree.
+There are expectations about which solution uv should choose, even if the version constraints allow
+multiple solutions. Generally, a desirable solution prioritizes use the highest versions for direct
+dependencies over those for indirect dependencies, it avoids backtracking to very old versions and
+can be installed on a target machine.
+Internally, uv represent each package with a given package name as a number of virtual packages, for
+example, one package for each activated extra, for dependency groups, or for having a marker. While
+PubGrub needs to choose a version for each virtual package, uv's prioritization works on the package
+name level.
+Whenever we encounter a requirement on a package, we match it to a priority. The root package and
+URL requirements have the highest priority, then singleton requirements with the == operator, as
+their version can be directly determined, then highly conflicting packages (next paragraph), and
+finally all other packages. Inside each category, packages are sorted by when they were first
+encountered, creating a breadth first search that prioritizes direct dependencies including
+workspace dependencies over transitive dependencies.
+A common problem is that we have a package A with a higher priority than package B, and B is only
+compatible with older versions of A. We decide the latest version for package A. Each time we decide
+a version for B, it is immediately discarded due to the conflict with A. We have to try all possible
+versions of B, until we have either exhausted the possible range (slow), pick a very old version
+that doesn't depend on A, but most likely isn't compatible with the project either (bad) or fail to
+build a very old version (bad). Once we see such conflict happen five time, we set A and B to
+special highly-conflicting priority levels, and set them so that B is decided before A. We then
+manually backtrack to a state before deciding A, in the next iteration now deciding B instead of A.
+See #8157 and
+#9843 for a more detailed description with real world
+examples.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/policies/index.html b/site/uv-next/reference/policies/index.html
new file mode 100644
index 000000000..985abb0c5
--- /dev/null
+++ b/site/uv-next/reference/policies/index.html
@@ -0,0 +1,3395 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Policies | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Policies
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/policies/license/index.html b/site/uv-next/reference/policies/license/index.html
new file mode 100644
index 000000000..27456a8ae
--- /dev/null
+++ b/site/uv-next/reference/policies/license/index.html
@@ -0,0 +1,3397 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+License | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+License
+uv is licensed under either of
+
+- Apache License, Version 2.0
+
+LICENSE-APACHE or
+ https://www.apache.org/licenses/LICENSE-2.0
+
+- MIT License
+
+LICENSE-MIT or
+ https://opensource.org/licenses/MIT
+at your option.
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in uv
+by you, as defined in the Apache-2.0 license, shall be dually licensed as above, without any
+additional terms or conditions.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/policies/platforms/index.html b/site/uv-next/reference/policies/platforms/index.html
new file mode 100644
index 000000000..113397b9d
--- /dev/null
+++ b/site/uv-next/reference/policies/platforms/index.html
@@ -0,0 +1,3553 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Platform support | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Platform support
+uv has Tier 1 support for the following platforms:
+
+- macOS (Apple Silicon)
+- macOS (x86_64)
+- Linux (x86_64)
+- Windows (x86_64)
+
+uv is continuously built, tested, and developed against its Tier 1 platforms. Inspired by the Rust
+project, Tier 1 can be thought of as
+"guaranteed to work".
+uv has Tier 2 support
+("guaranteed to build") for the
+following platforms:
+
+- Linux (PPC64)
+- Linux (PPC64LE)
+- Linux (RISC-V64)
+- Linux (aarch64)
+- Linux (armv7)
+- Linux (i686)
+- Linux (s390x)
+- Windows (arm64)
+
+uv ships pre-built wheels to PyPI for its Tier 1 and Tier 2
+platforms. However, while Tier 2 platforms are continuously built, they are not continuously tested
+or developed against, and so stability may vary in practice.
+Beyond the Tier 1 and Tier 2 platforms, uv is known to build on i686 Windows, and known not to
+build on aarch64 Windows, but does not consider either platform to be supported at this time. The
+minimum supported Windows versions are Windows 10 and Windows Server 2016, following
+Rust's own Tier 1 support.
+macOS versions
+uv supports macOS 13+ (Ventura).
+uv is known to work on macOS 12, but requires installation of a realpath executable.
+Python support
+uv supports and is tested against the following Python versions:
+
+- 3.8
+- 3.9
+- 3.10
+- 3.11
+- 3.12
+- 3.13
+- 3.14
+
+uv has Tier 1 support for the following Python implementations:
+
+- CPython
+
+As with platforms, Tier 1 support can be thought of "guaranteed to work". uv supports managed
+installations of these implementations, and the builds are maintained by Astral.
+uv has Tier 2 support for:
+
+- PyPy
+- GraalPy
+
+uv is "expected to work" with these implementations. uv also supports managed installations of these
+Python implementations, but the builds are not maintained by Astral.
+uv has Tier 3 support for:
+
+- Pyston
+- Pyodide
+
+uv "should work" with these implementations, but stability may vary.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/policies/versioning/index.html b/site/uv-next/reference/policies/versioning/index.html
new file mode 100644
index 000000000..d2c53eb3f
--- /dev/null
+++ b/site/uv-next/reference/policies/versioning/index.html
@@ -0,0 +1,3534 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Versioning | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Versioning
+uv uses a custom versioning scheme in which the minor version number is bumped for breaking changes,
+and the patch version number is bumped for bug fixes, enhancements, and other non-breaking changes.
+uv is widely used in production. However, we value the ability to iterate on new features quickly
+and gather changes that could be breaking into clearly marked releases.
+Once uv v1.0.0 is released, the versioning scheme will adhere to
+Semantic Versioning. There is not a particular goal that must be achieved for
+uv to reach this milestone.
+uv's changelog can be viewed on GitHub.
+Cache versioning
+Cache versions are considered internal to uv, and so may be changed in a minor or patch release. See
+Cache versioning for more.
+Lockfile versioning
+The uv.lock schema version is considered part of the public API, and so will only be incremented
+in a minor release as a breaking change. See
+Lockfile versioning for more.
+Minimum supported Rust version
+The minimum supported Rust version required to compile uv is listed in the rust-version key of the
+[workspace.package] section in Cargo.toml. It may change in any release (minor or patch). It
+will never be newer than N-2 Rust versions, where N is the latest stable version. For example, if
+the latest stable Rust version is 1.85, uv's minimum supported Rust version will be at most 1.83.
+This is only relevant to users who build uv from source. Installing uv from the Python package index
+usually installs a pre-built binary and does not require Rust compilation.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/settings/index.html b/site/uv-next/reference/settings/index.html
new file mode 100644
index 000000000..6aec7c9b8
--- /dev/null
+++ b/site/uv-next/reference/settings/index.html
@@ -0,0 +1,9661 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Settings | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Settings
+
+Project metadata
+build-constraint-dependencies
+Constraints to apply when solving build dependencies.
+Build constraints are used to restrict the versions of build dependencies that are selected
+when building a package during resolution or installation.
+Including a package as a constraint will not trigger installation of the package during
+a build; instead, the package must be requested elsewhere in the project's build dependency
+graph.
+
+Note
+In uv lock, uv sync, and uv run, uv will only read build-constraint-dependencies from
+the pyproject.toml at the workspace root, and will ignore any declarations in other
+workspace members or uv.toml files.
+
+Default value: []
+Type: list[str]
+Example usage:
+pyproject.toml[tool.uv]
+# Ensure that the setuptools v60.0.0 is used whenever a package has a build dependency
+# on setuptools.
+build-constraint-dependencies = ["setuptools==60.0.0"]
+
+
+conflicts
+Declare collections of extras or dependency groups that are conflicting
+(i.e., mutually exclusive).
+It's useful to declare conflicts when two or more extras have mutually
+incompatible dependencies. For example, extra foo might depend
+on numpy==2.0.0 while extra bar depends on numpy==2.1.0. While these
+dependencies conflict, it may be the case that users are not expected to
+activate both foo and bar at the same time, making it possible to
+generate a universal resolution for the project despite the incompatibility.
+By making such conflicts explicit, uv can generate a universal resolution
+for a project, taking into account that certain combinations of extras and
+groups are mutually exclusive. In exchange, installation will fail if a
+user attempts to activate both conflicting extras.
+Default value: []
+Type: list[list[dict]]
+Example usage:
+pyproject.toml[tool.uv]
+# Require that `package[extra1]` and `package[extra2]` are resolved
+# in different forks so that they cannot conflict with one another.
+conflicts = [
+ [
+ { extra = "extra1" },
+ { extra = "extra2" },
+ ]
+]
+
+# Require that the dependency groups `group1` and `group2`
+# are resolved in different forks so that they cannot conflict
+# with one another.
+conflicts = [
+ [
+ { group = "group1" },
+ { group = "group2" },
+ ]
+]
+
+
+constraint-dependencies
+Constraints to apply when resolving the project's dependencies.
+Constraints are used to restrict the versions of dependencies that are selected during
+resolution.
+Including a package as a constraint will not trigger installation of the package on its
+own; instead, the package must be requested elsewhere in the project's first-party or
+transitive dependencies.
+
+Note
+In uv lock, uv sync, and uv run, uv will only read constraint-dependencies from
+the pyproject.toml at the workspace root, and will ignore any declarations in other
+workspace members or uv.toml files.
+
+Default value: []
+Type: list[str]
+Example usage:
+pyproject.toml[tool.uv]
+# Ensure that the grpcio version is always less than 1.65, if it's requested by a
+# direct or transitive dependency.
+constraint-dependencies = ["grpcio<1.65"]
+
+
+default-groups
+The list of dependency-groups to install by default.
+Can also be the literal "all" to default enable all groups.
+Default value: ["dev"]
+Type: str | list[str]
+Example usage:
+
+
+dependency-groups
+Additional settings for dependency-groups.
+Currently this can only be used to add requires-python constraints
+to dependency groups (typically to inform uv that your dev tooling
+has a higher python requirement than your actual project).
+This cannot be used to define dependency groups, use the top-level
+[dependency-groups] table for that.
+Default value: []
+Type: dict
+Example usage:
+
+
+dev-dependencies
+The project's development dependencies.
+Development dependencies will be installed by default in uv run and uv sync, but will
+not appear in the project's published metadata.
+Use of this field is not recommend anymore. Instead, use the dependency-groups.dev field
+which is a standardized way to declare development dependencies. The contents of
+tool.uv.dev-dependencies and dependency-groups.dev are combined to determine the final
+requirements of the dev dependency group.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+environments
+A list of supported environments against which to resolve dependencies.
+By default, uv will resolve for all possible environments during a uv lock operation.
+However, you can restrict the set of supported environments to improve performance and avoid
+unsatisfiable branches in the solution space.
+These environments will also be respected when uv pip compile is invoked with the
+--universal flag.
+Default value: []
+Type: str | list[str]
+Example usage:
+pyproject.toml[tool.uv]
+# Resolve for macOS, but not for Linux or Windows.
+environments = ["sys_platform == 'darwin'"]
+
+
+exclude-dependencies
+Dependencies to exclude when resolving the project's dependencies.
+Excludes are used to prevent a package from being selected during resolution,
+regardless of whether it's requested by any other package. When a package is excluded,
+it will be omitted from the dependency list entirely.
+Including a package as an exclusion will prevent it from being installed, even if
+it's requested by transitive dependencies. This can be useful for removing optional
+dependencies or working around packages with broken dependencies.
+
+Note
+In uv lock, uv sync, and uv run, uv will only read exclude-dependencies from
+the pyproject.toml at the workspace root, and will ignore any declarations in other
+workspace members or uv.toml files.
+
+Default value: []
+Type: list[str]
+Example usage:
+pyproject.toml[tool.uv]
+# Exclude Werkzeug from being installed, even if transitive dependencies request it.
+exclude-dependencies = ["werkzeug"]
+
+
+index
+The indexes to use when resolving dependencies.
+Accepts either a repository compliant with PEP 503
+(the simple repository API), or a local directory laid out in the same format.
+Indexes are considered in the order in which they're defined, such that the first-defined
+index has the highest priority. Further, the indexes provided by this setting are given
+higher priority than any indexes specified via index_url or
+extra_index_url. uv will only consider the first index that contains
+a given package, unless an alternative index strategy is specified.
+If an index is marked as explicit = true, it will be used exclusively for the
+dependencies that select it explicitly via [tool.uv.sources], as in:
+[[tool.uv.index]]
+name = "pytorch"
+url = "https://download.pytorch.org/whl/cu121"
+explicit = true
+
+[tool.uv.sources]
+torch = { index = "pytorch" }
+
+If an index is marked as default = true, it will be moved to the end of the prioritized list, such that it is
+given the lowest priority when resolving packages. Additionally, marking an index as default will disable the
+PyPI default index.
+Default value: []
+Type: dict
+Example usage:
+
+
+managed
+Whether the project is managed by uv. If false, uv will ignore the project when
+uv run is invoked.
+Default value: true
+Type: bool
+Example usage:
+
+
+override-dependencies
+Overrides to apply when resolving the project's dependencies.
+Overrides are used to force selection of a specific version of a package, regardless of the
+version requested by any other package, and regardless of whether choosing that version
+would typically constitute an invalid resolution.
+While constraints are additive, in that they're combined with the requirements of the
+constituent packages, overrides are absolute, in that they completely replace the
+requirements of any constituent packages.
+Including a package as an override will not trigger installation of the package on its
+own; instead, the package must be requested elsewhere in the project's first-party or
+transitive dependencies.
+
+Note
+In uv lock, uv sync, and uv run, uv will only read override-dependencies from
+the pyproject.toml at the workspace root, and will ignore any declarations in other
+workspace members or uv.toml files.
+
+Default value: []
+Type: list[str]
+Example usage:
+pyproject.toml[tool.uv]
+# Always install Werkzeug 2.3.0, regardless of whether transitive dependencies request
+# a different version.
+override-dependencies = ["werkzeug==2.3.0"]
+
+
+package
+Whether the project should be considered a Python package, or a non-package ("virtual")
+project.
+Packages are built and installed into the virtual environment in editable mode and thus
+require a build backend, while virtual projects are not built or installed; instead, only
+their dependencies are included in the virtual environment.
+Creating a package requires that a build-system is present in the pyproject.toml, and
+that the project adheres to a structure that adheres to the build backend's expectations
+(e.g., a src layout).
+Default value: true
+Type: bool
+Example usage:
+
+
+required-environments
+A list of required platforms, for packages that lack source distributions.
+When a package does not have a source distribution, it's availability will be limited to
+the platforms supported by its built distributions (wheels). For example, if a package only
+publishes wheels for Linux, then it won't be installable on macOS or Windows.
+By default, uv requires each package to include at least one wheel that is compatible with
+the designated Python version. The required-environments setting can be used to ensure that
+the resulting resolution contains wheels for specific platforms, or fails if no such wheels
+are available.
+While the environments setting limits the set of environments that uv will consider when
+resolving dependencies, required-environments expands the set of platforms that uv must
+support when resolving dependencies.
+For example, environments = ["sys_platform == 'darwin'"] would limit uv to solving for
+macOS (and ignoring Linux and Windows). On the other hand, required-environments = ["sys_platform == 'darwin'"]
+would require that any package without a source distribution include a wheel for macOS in
+order to be installable.
+Default value: []
+Type: str | list[str]
+Example usage:
+pyproject.toml[tool.uv]
+# Require that the package is available for macOS ARM and x86 (Intel).
+required-environments = [
+ "sys_platform == 'darwin' and platform_machine == 'arm64'",
+ "sys_platform == 'darwin' and platform_machine == 'x86_64'",
+]
+
+
+sources
+The sources to use when resolving dependencies.
+tool.uv.sources enriches the dependency metadata with additional sources, incorporated
+during development. A dependency source can be a Git repository, a URL, a local path, or an
+alternative registry.
+See Dependencies for more.
+Default value: {}
+Type: dict
+Example usage:
+pyproject.toml[tool.uv.sources]
+httpx = { git = "https://github.com/encode/httpx", tag = "0.27.0" }
+pytest = { url = "https://files.pythonhosted.org/packages/6b/77/7440a06a8ead44c7757a64362dd22df5760f9b12dc5f11b6188cd2fc27a0/pytest-8.3.3-py3-none-any.whl" }
+pydantic = { path = "/path/to/pydantic", editable = true }
+
+
+build-backend
+Settings for the uv build backend (uv_build).
+Note that those settings only apply when using the uv_build backend, other build backends
+(such as hatchling) have their own configuration.
+All options that accept globs use the portable glob patterns from
+PEP 639.
+data
+
+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.
+Default value: {}
+Type: dict[str, str]
+Example usage:
+
+
+default-excludes
+
+If set to false, the default excludes aren't applied.
+Default excludes: __pycache__, *.pyc, and *.pyo.
+Default value: true
+Type: bool
+Example usage:
+
+
+module-name
+
+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.
+Default value: None
+Type: str | list[str]
+Example usage:
+
+
+module-root
+
+The directory that contains the module directory.
+Common values are src (src layout, the default) or an empty path (flat layout).
+Default value: "src"
+Type: str
+Example usage:
+
+
+namespace
+
+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
+
+Default value: false
+Type: bool
+Example usage:
+
+
+source-exclude
+
+Glob expressions which files and directories to exclude from the source distribution.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+source-include
+
+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.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+wheel-exclude
+
+Glob expressions which files and directories to exclude from the wheel.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+workspace
+exclude
+
+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.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+members
+
+Packages to include as workspace members.
+Supports both globs and explicit paths.
+For more information on the glob syntax, refer to the glob documentation.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+Configuration
+add-bounds
+The default version specifier when adding a dependency.
+When adding a dependency to the project, if no constraint or URL is provided, a constraint
+is added based on the latest compatible version of the package. By default, a lower bound
+constraint is used, e.g., >=1.2.3.
+When --frozen is provided, no resolution is performed, and dependencies are always added
+without constraints.
+This option is in preview and may change in any future release.
+Default value: "lower"
+Possible values:
+
+"lower": Only a lower bound, e.g., >=1.2.3"major": Allow the same major version, similar to the semver caret, e.g., >=1.2.3, <2.0.0"minor": Allow the same minor version, similar to the semver tilde, e.g., >=1.2.3, <1.3.0"exact": Pin the exact version, e.g., ==1.2.3
+Example usage:
+
+
+allow-insecure-host
+Allow insecure connections to host.
+Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g.,
+localhost:8080), or a URL (e.g., https://localhost).
+WARNING: Hosts included in this list will not be verified against the system's certificate
+store. Only use --allow-insecure-host in a secure network with verified sources, as it
+bypasses SSL verification and could expose you to MITM attacks.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+
+
+cache-dir
+Path to the cache directory.
+Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux and macOS, and
+%LOCALAPPDATA%\uv\cache on Windows.
+Default value: None
+Type: str
+Example usage:
+
+
+cache-keys
+The keys to consider when caching builds for the project.
+Cache keys enable you to specify the files or directories that should trigger a rebuild when
+modified. By default, uv will rebuild a project whenever the pyproject.toml, setup.py,
+or setup.cfg files in the project directory are modified, or if a src directory is
+added or removed, i.e.:
+cache-keys = [{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }, { dir = "src" }]
+
+As an example: if a project uses dynamic metadata to read its dependencies from a
+requirements.txt file, you can specify cache-keys = [{ file = "requirements.txt" }, { file = "pyproject.toml" }]
+to ensure that the project is rebuilt whenever the requirements.txt file is modified (in
+addition to watching the pyproject.toml).
+Globs are supported, following the syntax of the glob
+crate. For example, to invalidate the cache whenever a .toml file in the project directory
+or any of its subdirectories is modified, you can specify cache-keys = [{ file = "**/*.toml" }].
+Note that the use of globs can be expensive, as uv may need to walk the filesystem to
+determine whether any files have changed.
+Cache keys can also include version control information. For example, if a project uses
+setuptools_scm to read its version from a Git commit, you can specify cache-keys = [{ git = { commit = true }, { file = "pyproject.toml" }]
+to include the current Git commit hash in the cache key (in addition to the
+pyproject.toml). Git tags are also supported via cache-keys = [{ git = { commit = true, tags = true } }].
+Cache keys can also include environment variables. For example, if a project relies on
+MACOSX_DEPLOYMENT_TARGET or other environment variables to determine its behavior, you can
+specify cache-keys = [{ env = "MACOSX_DEPLOYMENT_TARGET" }] to invalidate the cache
+whenever the environment variable changes.
+Cache keys only affect the project defined by the pyproject.toml in which they're
+specified (as opposed to, e.g., affecting all members in a workspace), and all paths and
+globs are interpreted as relative to the project directory.
+Default value: [{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }]
+Type: list[dict]
+Example usage:
+
+
+
+
+check-url
+Check an index URL for existing files to skip duplicate uploads.
+This option allows retrying publishing that failed after only some, but not all files have
+been uploaded, and handles error due to parallel uploads of the same file.
+Before uploading, the index is checked. If the exact same file already exists in the index,
+the file will not be uploaded. If an error occurred during the upload, the index is checked
+again, to handle cases where the identical file was uploaded twice in parallel.
+The exact behavior will vary based on the index. When uploading to PyPI, uploading the same
+file succeeds even without --check-url, while most other indexes error.
+The index must provide one of the supported hashes (SHA-256, SHA-384, or SHA-512).
+Default value: None
+Type: str
+Example usage:
+
+
+
+
+compile-bytecode
+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.
+Default value: false
+Type: bool
+Example usage:
+
+
+concurrent-builds
+The maximum number of source distributions that uv will build concurrently at any given
+time.
+Defaults to the number of available CPU cores.
+Default value: None
+Type: int
+Example usage:
+
+
+concurrent-downloads
+The maximum number of in-flight concurrent downloads that uv will perform at any given
+time.
+Default value: 50
+Type: int
+Example usage:
+
+
+concurrent-installs
+The number of threads used when installing and unzipping packages.
+Defaults to the number of available CPU cores.
+Default value: None
+Type: int
+Example usage:
+
+
+config-settings
+Settings to pass to the PEP 517 build backend,
+specified as KEY=VALUE pairs.
+Default value: {}
+Type: dict
+Example usage:
+
+
+
+
+config-settings-package
+Settings to pass to the PEP 517 build backend for specific packages,
+specified as KEY=VALUE pairs.
+Accepts a map from package names to string key-value pairs.
+Default value: {}
+Type: dict
+Example usage:
+
+
+
+
+dependency-metadata
+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.
+
+Default value: []
+Type: list[dict]
+Example usage:
+
+
+
+
+exclude-newer
+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.
+Default value: None
+Type: str
+Example usage:
+
+
+
+
+exclude-newer-package
+Limit candidate packages for specific packages to those that were uploaded prior to the given date.
+Accepts package-date pairs in a dictionary format.
+Default value: None
+Type: dict
+Example usage:
+
+
+
+
+extra-build-dependencies
+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.
+Default value: []
+Type: dict
+Example usage:
+
+
+
+
+extra-build-variables
+Extra environment variables to set when building certain packages.
+Environment variables will be added to the environment when building the
+specified packages.
+Default value: {}
+Type: dict[str, dict[str, str]]
+Example usage:
+
+
+
+
+extra-index-url
+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 or index with default = true. When multiple indexes
+are provided, earlier values take priority.
+To control uv's resolution strategy when multiple indexes are present, see
+index_strategy.
+(Deprecated: use index instead.)
+Default value: []
+Type: list[str]
+Example usage:
+
+
+
+
+find-links
+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.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+
+
+fork-strategy
+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.
+Default value: "requires-python"
+Possible values:
+
+"fewest": Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms"requires-python": Optimize for selecting latest supported version of each package, for each supported Python version
+Example usage:
+
+
+index
+The package indexes to use when resolving dependencies.
+Accepts either a repository compliant with PEP 503
+(the simple repository API), or a local directory laid out in the same format.
+Indexes are considered in the order in which they're defined, such that the first-defined
+index has the highest priority. Further, the indexes provided by this setting are given
+higher priority than any indexes specified via index_url or
+extra_index_url. uv will only consider the first index that contains
+a given package, unless an alternative index strategy is specified.
+If an index is marked as explicit = true, it will be used exclusively for those
+dependencies that select it explicitly via [tool.uv.sources], as in:
+[[tool.uv.index]]
+name = "pytorch"
+url = "https://download.pytorch.org/whl/cu121"
+explicit = true
+
+[tool.uv.sources]
+torch = { index = "pytorch" }
+
+If an index is marked as default = true, it will be moved to the end of the prioritized list, such that it is
+given the lowest priority when resolving packages. Additionally, marking an index as default will disable the
+PyPI default index.
+Default value: "[]"
+Type: dict
+Example usage:
+
+
+
+
+index-strategy
+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.
+Default value: "first-index"
+Possible values:
+
+"first-index": Only use results from the first index that returns a match for a given package name"unsafe-first-match": Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next"unsafe-best-match": Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
+Example usage:
+
+
+
+
+index-url
+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 or index.
+(Deprecated: use index instead.)
+Default value: "https://pypi.org/simple"
+Type: str
+Example usage:
+
+
+
+
+keyring-provider
+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.
+Default value: "disabled"
+Type: str
+Example usage:
+
+
+link-mode
+The method to use when installing packages from the global cache.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and
+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.
+Default value: "clone" (macOS) or "hardlink" (Linux, Windows)
+Possible values:
+
+"clone": Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory"copy": Copy packages from the wheel into the site-packages directory"hardlink": Hard link packages from the wheel into the site-packages directory"symlink": Symbolically link packages from the wheel into the site-packages directory
+Example usage:
+
+
+native-tls
+Whether to load TLS certificates from the platform's native certificate store.
+By default, uv loads certificates from the bundled webpki-roots crate. The
+webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv
+improves portability and performance (especially on macOS).
+However, in some cases, you may want to use the platform's native certificate store,
+especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's
+included in your system's certificate store.
+Default value: false
+Type: bool
+Example usage:
+
+
+no-binary
+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.
+Default value: false
+Type: bool
+Example usage:
+
+
+no-binary-package
+Don't install pre-built wheels for a specific package.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+no-build
+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.
+Default value: false
+Type: bool
+Example usage:
+
+
+no-build-isolation
+Disable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518
+are already installed.
+Default value: false
+Type: bool
+Example usage:
+
+
+no-build-isolation-package
+Disable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518
+are already installed.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+
+
+no-build-package
+Don't build source distributions for a specific package.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+no-cache
+Avoid reading from or writing to the cache, instead using a temporary directory for the
+duration of the operation.
+Default value: false
+Type: bool
+Example usage:
+
+
+no-index
+Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and
+those provided via --find-links.
+Default value: false
+Type: bool
+Example usage:
+
+
+no-sources
+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.
+Default value: false
+Type: bool
+Example usage:
+
+
+offline
+Disable network access, relying only on locally cached data and locally available files.
+Default value: false
+Type: bool
+Example usage:
+
+
+prerelease
+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).
+Default value: "if-necessary-or-explicit"
+Possible values:
+
+"disallow": Disallow all pre-release versions"allow": Allow all pre-release versions"if-necessary": Allow pre-release versions if all versions of a package are pre-release"explicit": Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements"if-necessary-or-explicit": Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
+Example usage:
+
+
+preview
+Whether to enable experimental, preview features.
+Default value: false
+Type: bool
+Example usage:
+
+
+publish-url
+The URL for publishing packages to the Python package index (by default:
+https://upload.pypi.org/legacy/).
+Default value: "https://upload.pypi.org/legacy/"
+Type: str
+Example usage:
+
+
+
+
+pypy-install-mirror
+Mirror URL to use for downloading managed PyPy installations.
+By default, managed PyPy installations are downloaded from downloads.python.org.
+This variable can be set to a mirror URL to use a different source for PyPy installations.
+The provided URL will replace https://downloads.python.org/pypy in, e.g., https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2.
+Distributions can be read from a
+local directory by using the file:// URL scheme.
+Default value: None
+Type: str
+Example usage:
+
+
+
+
+python-downloads
+Whether to allow Python downloads.
+Default value: "automatic"
+Possible values:
+
+"automatic": Automatically download managed Python installations when needed"manual": Do not automatically download managed Python installations; require explicit installation"never": Do not ever allow Python downloads
+Example usage:
+
+
+python-downloads-json-url
+URL pointing to JSON of custom Python installations.
+Note that currently, only local paths are supported.
+Default value: None
+Type: str
+Example usage:
+
+
+
+
+python-install-mirror
+Mirror URL for downloading managed Python installations.
+By default, managed Python installations are downloaded from python-build-standalone.
+This variable can be set to a mirror URL to use a different source for Python installations.
+The provided URL will replace https://github.com/astral-sh/python-build-standalone/releases/download in, e.g., https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz.
+Distributions can be read from a local directory by using the file:// URL scheme.
+Default value: None
+Type: str
+Example usage:
+
+
+
+
+python-preference
+Whether to prefer using Python installations that are already present on the system, or
+those that are downloaded and installed by uv.
+Default value: "managed"
+Possible values:
+
+"only-managed": Only use managed Python installations; never use system Python installations"managed": Prefer managed Python installations over system Python installations"system": Prefer system Python installations over managed Python installations"only-system": Only use system Python installations; never use managed Python installations
+Example usage:
+
+
+reinstall
+Reinstall all packages, regardless of whether they're already installed. Implies refresh.
+Default value: false
+Type: bool
+Example usage:
+
+
+reinstall-package
+Reinstall a specific package, regardless of whether it's already installed. Implies
+refresh-package.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+required-version
+Enforce a requirement on the version of uv.
+If the version of uv does not meet the requirement at runtime, uv will exit
+with an error.
+Accepts a PEP 440 specifier, like ==0.5.0 or >=0.5.0.
+Default value: null
+Type: str
+Example usage:
+
+
+resolution
+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).
+Default value: "highest"
+Possible values:
+
+"highest": Resolve the highest compatible version of each package"lowest": Resolve the lowest compatible version of each package"lowest-direct": Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
+Example usage:
+
+
+trusted-publishing
+Configure trusted publishing.
+By default, uv checks for trusted publishing when running in a supported environment, but
+ignores it if it isn't configured.
+uv's supported environments for trusted publishing include GitHub Actions and GitLab CI/CD.
+Default value: automatic
+Type: str
+Example usage:
+
+
+upgrade
+Allow package upgrades, ignoring pinned versions in any existing output file.
+Default value: false
+Type: bool
+Example usage:
+
+
+upgrade-package
+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).
+Default value: []
+Type: list[str]
+Example usage:
+
+
+pip
+Settings that are specific to the uv pip command-line interface.
+These values will be ignored when running commands outside the uv pip namespace (e.g.,
+uv lock, uvx).
+all-extras
+
+Include all optional dependencies.
+Only applies to pyproject.toml, setup.py, and setup.cfg sources.
+Default value: false
+Type: bool
+Example usage:
+
+
+allow-empty-requirements
+
+Allow uv pip sync with empty requirements, which will clear the environment of all
+packages.
+Default value: false
+Type: bool
+Example usage:
+
+
+
+
+annotation-style
+
+The style of the annotation comments included in the output file, used to indicate the
+source of each package.
+Default value: "split"
+Possible values:
+
+"line": Render the annotations on a single, comma-separated line"split": Render each annotation on its own line
+Example usage:
+
+
+break-system-packages
+
+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).
+Default value: false
+Type: bool
+Example usage:
+
+
+compile-bytecode
+
+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.
+Default value: false
+Type: bool
+Example usage:
+
+
+config-settings
+
+Settings to pass to the PEP 517 build backend,
+specified as KEY=VALUE pairs.
+Default value: {}
+Type: dict
+Example usage:
+
+
+
+
+config-settings-package
+
+Settings to pass to the PEP 517 build backend for specific packages,
+specified as KEY=VALUE pairs.
+Default value: {}
+Type: dict
+Example usage:
+
+
+
+
+custom-compile-command
+
+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.
+Default value: None
+Type: str
+Example usage:
+
+
+
+
+dependency-metadata
+
+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.
+
+Default value: []
+Type: list[dict]
+Example usage:
+
+
+
+
+emit-build-options
+
+Include --no-binary and --only-binary entries in the output file generated by uv pip compile.
+Default value: false
+Type: bool
+Example usage:
+
+
+emit-find-links
+
+Include --find-links entries in the output file generated by uv pip compile.
+Default value: false
+Type: bool
+Example usage:
+
+
+emit-index-annotation
+
+Include comment annotations indicating the index used to resolve each package (e.g.,
+# from https://pypi.org/simple).
+Default value: false
+Type: bool
+Example usage:
+
+
+emit-index-url
+
+Include --index-url and --extra-index-url entries in the output file generated by uv pip compile.
+Default value: false
+Type: bool
+Example usage:
+
+
+emit-marker-expression
+
+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.
+Default value: false
+Type: bool
+Example usage:
+
+
+
+
+exclude-newer
+
+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.
+Default value: None
+Type: str
+Example usage:
+
+
+
+
+exclude-newer-package
+
+Limit candidate packages for specific packages to those that were uploaded prior to the given date.
+Accepts package-date pairs in a dictionary format.
+Default value: None
+Type: dict
+Example usage:
+
+
+
+
+extra
+
+Include optional dependencies from the specified extra; may be provided more than once.
+Only applies to pyproject.toml, setup.py, and setup.cfg sources.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+extra-build-dependencies
+
+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.
+Default value: []
+Type: dict
+Example usage:
+
+
+
+
+extra-build-variables
+
+Extra environment variables to set when building certain packages.
+Environment variables will be added to the environment when building the
+specified packages.
+Default value: {}
+Type: dict[str, dict[str, str]]
+Example usage:
+
+
+
+
+extra-index-url
+
+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.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+
+
+find-links
+
+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.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+
+
+fork-strategy
+
+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.
+Default value: "requires-python"
+Possible values:
+
+"fewest": Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms"requires-python": Optimize for selecting latest supported version of each package, for each supported Python version
+Example usage:
+
+
+generate-hashes
+
+Include distribution hashes in the output file.
+Default value: false
+Type: bool
+Example usage:
+
+
+group
+
+Include the following dependency groups.
+Default value: None
+Type: list[str]
+Example usage:
+
+
+index-strategy
+
+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.
+Default value: "first-index"
+Possible values:
+
+"first-index": Only use results from the first index that returns a match for a given package name"unsafe-first-match": Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next"unsafe-best-match": Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
+Example usage:
+
+
+
+
+index-url
+
+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.
+Default value: "https://pypi.org/simple"
+Type: str
+Example usage:
+
+
+
+
+keyring-provider
+
+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.
+Default value: disabled
+Type: str
+Example usage:
+
+
+
+
+link-mode
+
+The method to use when installing packages from the global cache.
+Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and
+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.
+Default value: "clone" (macOS) or "hardlink" (Linux, Windows)
+Possible values:
+
+"clone": Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory"copy": Copy packages from the wheel into the site-packages directory"hardlink": Hard link packages from the wheel into the site-packages directory"symlink": Symbolically link packages from the wheel into the site-packages directory
+Example usage:
+
+
+no-annotate
+
+Exclude comment annotations indicating the source of each package from the output file
+generated by uv pip compile.
+Default value: false
+Type: bool
+Example usage:
+
+
+no-binary
+
+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:.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+no-build
+
+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:.
+Default value: false
+Type: bool
+Example usage:
+
+
+no-build-isolation
+
+Disable isolation when building source distributions.
+Assumes that build dependencies specified by PEP 518
+are already installed.
+Default value: false
+Type: bool
+Example usage:
+
+
+no-build-isolation-package
+
+Disable isolation when building source distributions for a specific package.
+Assumes that the packages' build dependencies specified by PEP 518
+are already installed.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+
+
+no-deps
+
+Ignore package dependencies, instead only add those packages explicitly listed
+on the command line to the resulting requirements file.
+Default value: false
+Type: bool
+Example usage:
+
+
+no-emit-package
+
+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.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+no-extra
+
+Exclude the specified optional dependencies if all-extras is supplied.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+
+
+no-header
+
+Exclude the comment header at the top of output file generated by uv pip compile.
+Default value: false
+Type: bool
+Example usage:
+
+
+no-index
+
+Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and
+those provided via --find-links.
+Default value: false
+Type: bool
+Example usage:
+
+
+no-sources
+
+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.
+Default value: false
+Type: bool
+Example usage:
+
+
+no-strip-extras
+
+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.
+Default value: false
+Type: bool
+Example usage:
+
+
+no-strip-markers
+
+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.
+Default value: false
+Type: bool
+Example usage:
+
+
+only-binary
+
+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:.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+output-file
+
+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.
+Default value: None
+Type: str
+Example usage:
+
+
+
+
+prefix
+
+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.
+Default value: None
+Type: str
+Example usage:
+
+
+prerelease
+
+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).
+Default value: "if-necessary-or-explicit"
+Possible values:
+
+"disallow": Disallow all pre-release versions"allow": Allow all pre-release versions"if-necessary": Allow pre-release versions if all versions of a package are pre-release"explicit": Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements"if-necessary-or-explicit": Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
+Example usage:
+
+
+python
+
+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.
+Default value: None
+Type: str
+Example usage:
+
+
+python-platform
+
+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.
+Default value: None
+Type: str
+Example usage:
+
+
+
+
+python-version
+
+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.
+Default value: None
+Type: str
+Example usage:
+
+
+reinstall
+
+Reinstall all packages, regardless of whether they're already installed. Implies refresh.
+Default value: false
+Type: bool
+Example usage:
+
+
+reinstall-package
+
+Reinstall a specific package, regardless of whether it's already installed. Implies
+refresh-package.
+Default value: []
+Type: list[str]
+Example usage:
+
+
+require-hashes
+
+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.
+
+Default value: false
+Type: bool
+Example usage:
+
+
+resolution
+
+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).
+Default value: "highest"
+Possible values:
+
+"highest": Resolve the highest compatible version of each package"lowest": Resolve the lowest compatible version of each package"lowest-direct": Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
+Example usage:
+
+
+strict
+
+Validate the Python environment, to detect packages with missing dependencies and other
+issues.
+Default value: false
+Type: bool
+Example usage:
+
+
+system
+
+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.
+Default value: false
+Type: bool
+Example usage:
+
+
+target
+
+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.
+Default value: None
+Type: str
+Example usage:
+
+
+torch-backend
+
+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 option is in preview and may change in any future release.
+Default value: null
+Type: str
+Example usage:
+
+
+universal
+
+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.
+Default value: false
+Type: bool
+Example usage:
+
+
+upgrade
+
+Allow package upgrades, ignoring pinned versions in any existing output file.
+Default value: false
+Type: bool
+Example usage:
+
+
+upgrade-package
+
+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).
+Default value: []
+Type: list[str]
+Example usage:
+
+
+verify-hashes
+
+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.
+Default value: true
+Type: bool
+Example usage:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/troubleshooting/build-failures/index.html b/site/uv-next/reference/troubleshooting/build-failures/index.html
new file mode 100644
index 000000000..16b05f292
--- /dev/null
+++ b/site/uv-next/reference/troubleshooting/build-failures/index.html
@@ -0,0 +1,3985 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Troubleshooting build failures | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Troubleshooting build failures
+uv needs to build packages when there is not a compatible wheel (a pre-built distribution of the
+package) available. Building packages can fail for many reasons, some of which may be unrelated to
+uv itself.
+Recognizing a build failure
+An example build failure can be produced by trying to install and old version of numpy on a new,
+unsupported version of Python:
+$ uv pip install -p 3.13 'numpy<1.20'
+Resolved 1 package in 62ms
+ × Failed to build `numpy==1.19.5`
+ ├─▶ The build backend returned an error
+ ╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel()` failed (exit status: 1)
+
+ [stderr]
+ Traceback (most recent call last):
+ File "<string>", line 8, in <module>
+ from setuptools.build_meta import __legacy__ as backend
+ File "/home/konsti/.cache/uv/builds-v0/.tmpi4bgKb/lib/python3.13/site-packages/setuptools/__init__.py", line 9, in <module>
+ import distutils.core
+ ModuleNotFoundError: No module named 'distutils'
+
+ hint: `distutils` was removed from the standard library in Python 3.12. Consider adding a constraint (like `numpy >1.19.5`) to avoid building a version of `numpy` that depends
+ on `distutils`.
+
+Notice that the error message is prefaced by "The build backend returned an error".
+The build failure includes the [stderr] (and [stdout], if present) from the build backend that
+was used for the build. The error logs are not from uv itself.
+The message following the ╰─▶ is a hint provided by uv, to help resolve common build failures. A
+hint will not be available for all build failures.
+Confirming that a build failure is specific to uv
+Build failures are usually related to your system and the build backend. It is rare that a build
+failure is specific to uv. You can confirm that the build failure is not related to uv by attempting
+to reproduce it with pip:
+$ uv venv -p 3.13 --seed
+$ source .venv/bin/activate
+$ pip install --use-pep517 --no-cache --force-reinstall 'numpy==1.19.5'
+Collecting numpy==1.19.5
+ Using cached numpy-1.19.5.zip (7.3 MB)
+ Installing build dependencies ... done
+ Getting requirements to build wheel ... done
+ERROR: Exception:
+Traceback (most recent call last):
+ ...
+ File "/Users/example/.cache/uv/archive-v0/3783IbOdglemN3ieOULx2/lib/python3.13/site-packages/pip/_vendor/pyproject_hooks/_impl.py", line 321, in _call_hook
+ raise BackendUnavailable(data.get('traceback', ''))
+pip._vendor.pyproject_hooks._impl.BackendUnavailable: Traceback (most recent call last):
+ File "/Users/example/.cache/uv/archive-v0/3783IbOdglemN3ieOULx2/lib/python3.13/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 77, in _build_backend
+ obj = import_module(mod_path)
+ File "/Users/example/.local/share/uv/python/cpython-3.13.0-macos-aarch64-none/lib/python3.13/importlib/__init__.py", line 88, in import_module
+ return _bootstrap._gcd_import(name[level:], package, level)
+ ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
+ File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
+ File "<frozen importlib._bootstrap>", line 1310, in _find_and_load_unlocked
+ File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
+ File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
+ File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
+ File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
+ File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
+ File "<frozen importlib._bootstrap_external>", line 1022, in exec_module
+ File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
+ File "/private/var/folders/6p/k5sd5z7j31b31pq4lhn0l8d80000gn/T/pip-build-env-vdpjme7d/overlay/lib/python3.13/site-packages/setuptools/__init__.py", line 9, in <module>
+ import distutils.core
+ModuleNotFoundError: No module named 'distutils'
+
+
+Important
+The --use-pep517 flag should be included with the pip install invocation to ensure the same
+build isolation behavior. uv always uses build isolation by default.
+We also recommend including the --force-reinstall and --no-cache options when reproducing
+failures.
+
+Since this build failure occurs in pip too, it is not likely to be a bug with uv.
+If a build failure is reproducible with another installer, you should investigate upstream (in this
+example, numpy or setuptools), find a way to avoid building the package in the first place, or
+make the necessary adjustments to your system for the build to succeed.
+Why does uv build a package?
+When generating the cross-platform lockfile, uv needs to determine the dependencies of all packages,
+even those only installed on other platforms. uv tries to avoid package builds during resolution. It
+uses any wheel if exist for that version, then tries to find static metadata in the source
+distribution (mainly pyproject.toml with static project.version, project.dependencies and
+project.optional-dependencies or METADATA v2.2+). Only if all of that fails, it builds the
+package.
+When installing, uv needs to have a wheel for the current platform for each package. If no matching
+wheel exists in the index, uv tries to build the source distribution.
+You can check which wheels exist for a PyPI project under “Download Files”, e.g.
+https://pypi.org/project/numpy/2.1.1.md#files. Wheels with ...-py3-none-any.whl filenames work
+everywhere, others have the operating system and platform in the filename. In the linked numpy
+example, you can see that there are pre-built distributions for Python 3.10 to 3.13 on macOS, Linux
+and Windows.
+Common build failures
+The following examples demonstrate common build failures and how to resolve them.
+Command is not found
+If the build error mentions a missing command, for example, gcc:
+
+
+× Failed to build `pysha3==1.0.2`
+├─▶ The build backend returned an error
+╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)
+
+ [stdout]
+ running bdist_wheel
+ running build
+ running build_py
+ creating build/lib.linux-x86_64-cpython-310
+ copying sha3.py -> build/lib.linux-x86_64-cpython-310
+ running build_ext
+ building '_pysha3' extension
+ creating build/temp.linux-x86_64-cpython-310/Modules/_sha3
+ gcc -Wno-unused-result -Wsign-compare -DNDEBUG -g -fwrapv -O3 -Wall -fPIC -DPY_WITH_KECCAK=1 -I/root/.cache/uv/builds-v0/.tmp8V4iEk/include -I/usr/local/include/python3.10 -c
+ Modules/_sha3/sha3module.c -o build/temp.linux-x86_64-cpython-310/Modules/_sha3/sha3module.o
+
+ [stderr]
+ error: command 'gcc' failed: No such file or directory
+
+Then, you'll need to install it with your system package manager, e.g., to resolve the error above:
+
+
+Tip
+When using the uv-managed Python versions, it's common to need clang installed instead of
+gcc.
+Many Linux distributions provide a package that includes all the common build dependencies.
+You can address most build requirements by installing it, e.g., for Debian or Ubuntu:
+
+
+Header or library is missing
+If the build error mentions a missing header or library, e.g., a .h file, then you'll need to
+install it with your system package manager.
+For example, installing pygraphviz requires Graphviz to be installed:
+
+
+× Failed to build `pygraphviz==1.14`
+├─▶ The build backend returned an error
+╰─▶ Call to `setuptools.build_meta.build_wheel` failed (exit status: 1)
+
+ [stdout]
+ running bdist_wheel
+ running build
+ running build_py
+ ...
+ gcc -fno-strict-overflow -Wsign-compare -DNDEBUG -g -O3 -Wall -fPIC -DSWIG_PYTHON_STRICT_BYTE_CHAR -I/root/.cache/uv/builds-v0/.tmpgLYPe0/include -I/usr/local/include/python3.12 -c pygraphviz/graphviz_wrap.c -o
+ build/temp.linux-x86_64-cpython-312/pygraphviz/graphviz_wrap.o
+
+ [stderr]
+ ...
+ pygraphviz/graphviz_wrap.c:9: warning: "SWIG_PYTHON_STRICT_BYTE_CHAR" redefined
+ 9 | #define SWIG_PYTHON_STRICT_BYTE_CHAR
+ |
+ <command-line>: note: this is the location of the previous definition
+ pygraphviz/graphviz_wrap.c:3023:10: fatal error: graphviz/cgraph.h: No such file or directory
+ 3023 | #include "graphviz/cgraph.h"
+ | ^~~~~~~~~~~~~~~~~~~
+ compilation terminated.
+ error: command '/usr/bin/gcc' failed with exit code 1
+
+ hint: This error likely indicates that you need to install a library that provides "graphviz/cgraph.h" for `pygraphviz@1.14`
+
+To resolve this error on Debian, you'd install the libgraphviz-dev package:
+
+Note that installing the graphviz package is not sufficient, the development headers need to be
+installed.
+
+Tip
+To resolve an error where Python.h is missing, install the python3-dev package.
+
+Module is missing or cannot be imported
+If the build error mentions a failing import, consider
+disabling build isolation.
+For example, some packages assume that pip is available without declaring it as a build
+dependency:
+
+
+ × Failed to build `chumpy==0.70`
+ ├─▶ The build backend returned an error
+ ╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)
+
+ [stderr]
+ Traceback (most recent call last):
+ File "<string>", line 9, in <module>
+ ModuleNotFoundError: No module named 'pip'
+
+ During handling of the above exception, another exception occurred:
+
+ Traceback (most recent call last):
+ File "<string>", line 14, in <module>
+ File "/root/.cache/uv/builds-v0/.tmpvvHaxI/lib/python3.12/site-packages/setuptools/build_meta.py", line 334, in get_requires_for_build_wheel
+ return self._get_build_requires(config_settings, requirements=[])
+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ File "/root/.cache/uv/builds-v0/.tmpvvHaxI/lib/python3.12/site-packages/setuptools/build_meta.py", line 304, in _get_build_requires
+ self.run_setup()
+ File "/root/.cache/uv/builds-v0/.tmpvvHaxI/lib/python3.12/site-packages/setuptools/build_meta.py", line 522, in run_setup
+ super().run_setup(setup_script=setup_script)
+ File "/root/.cache/uv/builds-v0/.tmpvvHaxI/lib/python3.12/site-packages/setuptools/build_meta.py", line 320, in run_setup
+ exec(code, locals())
+ File "<string>", line 11, in <module>
+ ModuleNotFoundError: No module named 'pip'
+
+To resolve this error, pre-install the build dependencies then disable build isolation for the
+package:
+
+Note you will need to install the missing package, e.g., pip, and all the other build
+dependencies of the package, e.g, setuptools.
+Old version of the package is built
+If a package fails to build during resolution and the version that failed to build is older than the
+version you want to use, try adding a constraint with a
+lower bound (e.g., numpy>=1.17). Sometimes, due to algorithmic limitations, the uv resolver tries
+to find a fitting version using unreasonably old packages, which can be prevented by using lower
+bounds.
+For example, when resolving the following dependencies on Python 3.10, uv attempts to build an old
+version of apache-beam.
+
+
+
+× Failed to build `apache-beam==2.0.0`
+├─▶ The build backend returned an error
+╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)
+
+ [stderr]
+ ...
+
+Adding a lower bound constraint, e.g., apache-beam<=2.49.0,>2.30.0, resolves this build failure as
+uv will avoid using an old version of apache-beam.
+Constraints can also be defined for indirect dependencies using constraints.txt files or the
+constraint-dependencies setting.
+Old Version of a build dependency is used
+If a package fails to build because uv selects an incompatible or outdated version of a build-time
+dependency, you can enforce constraints specifically for build dependencies. The
+build-constraint-dependencies setting (or an
+analogous build-constraints.txt file) can be used to ensure that uv selects an appropriate
+version of a given build requirements.
+For example, the issue described in
+#5551 could be addressed by
+specifying a build constraint that excludes setuptools version 72.0.0:
+pyproject.toml[tool.uv]
+# Prevent setuptools version 72.0.0 from being used as a build dependency.
+build-constraint-dependencies = ["setuptools!=72.0.0"]
+
+The build constraint will thus ensure that any package requiring setuptools during the build
+process will avoid using the problematic version, preventing build failures caused by incompatible
+build dependencies.
+Package is only needed for an unused platform
+If locking fails due to building a package from a platform you do not need to support, consider
+limiting resolution to your
+supported platforms.
+Package does not support all Python versions
+If you support a large range of Python versions, consider using markers to use older versions for
+older Python versions and newer versions for newer Python version. For example, numpy only
+supports four Python minor version at a time, so to support a wider range of Python versions, e.g.,
+Python 3.8 to 3.13, the numpy requirement needs to be split:
+
+Package is only usable on a specific platform
+If locking fails due to building a package that is only usable on another platform, you can
+provide dependency metadata manually to skip the build. uv can
+not verify this information, so it is important to specify correct metadata when using this
+override.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/troubleshooting/index.html b/site/uv-next/reference/troubleshooting/index.html
new file mode 100644
index 000000000..a1d2a1b74
--- /dev/null
+++ b/site/uv-next/reference/troubleshooting/index.html
@@ -0,0 +1,3396 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Troubleshooting | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Troubleshooting
+The troubleshooting section provides information about investigating failures in uv:
+
+- Build failures: Understanding common causes of package build failures.
+- Reproducible examples: How to write a minimal reproducible example
+ for a uv issue.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/reference/troubleshooting/reproducible-examples/index.html b/site/uv-next/reference/troubleshooting/reproducible-examples/index.html
new file mode 100644
index 000000000..d3ade244c
--- /dev/null
+++ b/site/uv-next/reference/troubleshooting/reproducible-examples/index.html
@@ -0,0 +1,3701 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Reproducible examples | uv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Skip to content
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Reproducible examples
+Why reproducible examples are important
+A minimal reproducible example (MRE) is essential for fixing bugs. Without an example that can be
+used to reproduce the problem, a maintainer cannot debug it or test if it is fixed. If the example
+is not minimal, i.e., if it includes lots of content which is not related to the issue, it can take
+a maintainer much longer to identify the root cause of the problem.
+How to write a reproducible example
+When writing a reproducible example, the goal is to provide all the context necessary for someone
+else to reproduce your example. This includes:
+
+- The platform you're using (e.g., the operating system and architecture)
+- Any relevant system state (e.g., explicitly set environment variables)
+- The version of uv
+- The version of other relevant tools
+- The relevant files (the
uv.lock, pyproject.toml, etc.)
+- The commands to run
+
+To ensure your reproduction is minimal, remove as many dependencies, settings, and files as
+possible. Be sure to test your reproduction before sharing it. We recommend including verbose logs
+from your reproduction; they may differ on your machine in a critical way. Using a
+Gist can be helpful for very long logs.
+Below, we'll cover several specific strategies for creating
+and sharing reproducible examples.
+
+Tip
+There's a great guide to the basics of creating MREs on
+Stack Overflow.
+
+Strategies for reproducible examples
+Docker image
+Writing a Docker image is often the best way to share a reproducible example because it is entirely
+self-contained. This means that the state from the reproducer's system does not affect the problem.
+
+Note
+Using a Docker image is only feasible if the issue is reproducible on Linux. When using macOS,
+it's prudent to ensure your image is not reproducible on Linux but some bugs are specific
+to the operating system. While using Docker to run Windows containers is feasible, it's not
+commonplace. These sorts of bugs are expected to be reported as a script instead.
+
+When writing a Docker MRE with uv, it's best to start with one of
+uv's Docker images. When doing so, be sure to
+pin to a specific version of uv.
+
+While Docker images are isolated from the system, the build will use your system's architecture by
+default. When sharing a reproduction, you can explicitly set the platform to ensure a reproducer
+gets the expected behavior. uv publishes images for linux/amd64 (e.g., Intel or AMD) and
+linux/arm64 (e.g., Apple M Series or ARM)
+
+Docker images are best for reproducing issues that can be constructed with commands, e.g.:
+FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.5.24-debian-slim
+
+RUN uv init /mre
+WORKDIR /mre
+RUN uv add pydantic
+RUN uv sync
+RUN uv run -v python -c "import pydantic"
+
+However, you can also write files into the image inline:
+FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.5.24-debian-slim
+
+COPY <<EOF /mre/pyproject.toml
+[project]
+name = "example"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["pydantic"]
+EOF
+
+WORKDIR /mre
+RUN uv lock
+
+If you need to write many files, it's better to create and publish a
+Git repository. You can combine these approaches and include a Dockerfile in
+the repository.
+When sharing a Docker reproduction, it's helpful to include the build logs. You can see more output
+from the build steps by disabling caching and the fancy output:
+
+Script
+When reporting platform-specific bugs that cannot be reproduced in a container,
+it's best practice to include a script showing the commands that can be used to reproduce the bug,
+e.g.:
+
+If your reproduction requires many files, use a Git repository to share them.
+In addition to the script, include verbose logs (i.e., with the -v flag) of the failure and the
+complete error message.
+Whenever a script relies on external state, be sure to share that information. For example, if you
+wrote the script on Windows, and it uses a Python version that you installed with choco and runs
+on PowerShell 6.2, please include that in the report.
+Git repository
+When sharing a Git repository reproduction, include a script that reproduces the problem
+or, even better, a Dockerfile. The first step of the script should be to clone the
+repository and checkout a specific commit:
+$ git clone https://github.com/<user>/<project>.git
+$ cd <project>
+$ git checkout <commit>
+$ <commands to produce error>
+
+You can quickly create a new repository in the GitHub UI or with the gh
+CLI:
+
+When using a Git repository for a reproduction, please remember to minimize the contents by
+excluding files or settings that are not required to reproduce your problem.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/site/uv-next/requirements.in b/site/uv-next/requirements.in
new file mode 100644
index 000000000..724270412
--- /dev/null
+++ b/site/uv-next/requirements.in
@@ -0,0 +1,8 @@
+black>=23.10.0
+zensical>=0.0.5
+mdformat>=0.7.17
+mdformat-mkdocs>=2.0.4
+mdformat-admon>=2.0.2
+mkdocs-redirects>=1.2.2
+mkdocs-git-revision-date-localized-plugin>=1.3.0
+mkdocs-llmstxt>=0.2.0
diff --git a/site/uv-next/requirements.txt b/site/uv-next/requirements.txt
new file mode 100644
index 000000000..d11365568
--- /dev/null
+++ b/site/uv-next/requirements.txt
@@ -0,0 +1,137 @@
+# This file was autogenerated by uv via the following command:
+# uv pip compile docs/requirements.in -o docs/requirements.txt --universal -p 3.12
+babel==2.15.0
+ # via mkdocs-git-revision-date-localized-plugin
+beautifulsoup4==4.13.4
+ # via
+ # markdownify
+ # mkdocs-llmstxt
+black==24.4.2
+ # via -r docs/requirements.in
+click==8.3.0
+ # via
+ # black
+ # mkdocs
+ # zensical
+colorama==0.4.6 ; sys_platform == 'win32'
+ # via
+ # click
+ # mkdocs
+deepmerge==2.0
+ # via zensical
+ghp-import==2.1.0
+ # via mkdocs
+gitdb==4.0.12
+ # via gitpython
+gitpython==3.1.44
+ # via mkdocs-git-revision-date-localized-plugin
+jinja2==3.1.4
+ # via mkdocs
+linkify-it-py==2.0.3
+ # via markdown-it-py
+markdown==3.10
+ # via
+ # mkdocs
+ # pymdown-extensions
+ # zensical
+markdown-it-py==3.0.0
+ # via
+ # mdformat
+ # mdformat-gfm
+ # mdit-py-plugins
+markdownify==1.1.0
+ # via mkdocs-llmstxt
+markupsafe==2.1.5
+ # via
+ # jinja2
+ # mkdocs
+mdformat==0.7.22
+ # via
+ # -r docs/requirements.in
+ # mdformat-admon
+ # mdformat-gfm
+ # mdformat-mkdocs
+ # mdformat-tables
+ # mkdocs-llmstxt
+mdformat-admon==2.0.6
+ # via
+ # -r docs/requirements.in
+ # mdformat-mkdocs
+mdformat-gfm==0.3.6
+ # via mdformat-mkdocs
+mdformat-mkdocs==3.0.0
+ # via -r docs/requirements.in
+mdformat-tables==0.4.1
+ # via mdformat-gfm
+mdit-py-plugins==0.4.1
+ # via
+ # mdformat-admon
+ # mdformat-gfm
+ # mdformat-mkdocs
+mdurl==0.1.2
+ # via markdown-it-py
+mergedeep==1.3.4
+ # via
+ # mkdocs
+ # mkdocs-get-deps
+mkdocs==1.6.0
+ # via
+ # mkdocs-git-revision-date-localized-plugin
+ # mkdocs-redirects
+mkdocs-get-deps==0.2.0
+ # via mkdocs
+mkdocs-git-revision-date-localized-plugin==1.3.0
+ # via -r docs/requirements.in
+mkdocs-llmstxt==0.2.0
+ # via -r docs/requirements.in
+mkdocs-redirects==1.2.2
+ # via -r docs/requirements.in
+more-itertools==10.3.0
+ # via mdformat-mkdocs
+mypy-extensions==1.0.0
+ # via black
+packaging==24.1
+ # via
+ # black
+ # mkdocs
+pathspec==0.12.1
+ # via
+ # black
+ # mkdocs
+platformdirs==4.2.2
+ # via
+ # black
+ # mkdocs-get-deps
+pygments==2.18.0
+ # via zensical
+pymdown-extensions==10.16.1
+ # via zensical
+python-dateutil==2.9.0.post0
+ # via ghp-import
+pytz==2025.1
+ # via mkdocs-git-revision-date-localized-plugin
+pyyaml==6.0.3
+ # via
+ # mkdocs
+ # mkdocs-get-deps
+ # pymdown-extensions
+ # pyyaml-env-tag
+ # zensical
+pyyaml-env-tag==0.1
+ # via mkdocs
+six==1.16.0
+ # via
+ # markdownify
+ # python-dateutil
+smmap==5.0.2
+ # via gitdb
+soupsieve==2.7
+ # via beautifulsoup4
+typing-extensions==4.14.0
+ # via beautifulsoup4
+uc-micro-py==1.0.3
+ # via linkify-it-py
+watchdog==4.0.1
+ # via mkdocs
+zensical==0.0.5
+ # via -r docs/requirements.in
diff --git a/site/uv-next/search.json b/site/uv-next/search.json
new file mode 100644
index 000000000..66de34b54
--- /dev/null
+++ b/site/uv-next/search.json
@@ -0,0 +1 @@
+{"config":{"separator":"[\\s\\-_,:!=\\[\\]()\\\\\"`/]+|\\.(?!\\d)"},"items":[{"location":"","level":1,"title":"uv","text":"An extremely fast Python package and project manager, written in Rust.
Installing Trio's dependencies with a warm cache.
","path":["uv"],"tags":[]},{"location":"#highlights","level":2,"title":"Highlights","text":" - 🚀 A single tool to replace
pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more. - ⚡️ 10-100x faster than
pip. - 🗂️ Provides comprehensive project management, with a universal lockfile.
- ❇️ Runs scripts, with support for inline dependency metadata.
- 🐍 Installs and manages Python versions.
- 🛠️ Runs and installs tools published as Python packages.
- 🔩 Includes a pip-compatible interface for a performance boost with a familiar CLI.
- 🏢 Supports Cargo-style workspaces for scalable projects.
- 💾 Disk-space efficient, with a global cache for dependency deduplication.
- ⏬ Installable without Rust or Python via
curl or pip. - 🖥️ Supports macOS, Linux, and Windows.
uv is backed by Astral, the creators of Ruff.
","path":["uv"],"tags":[]},{"location":"#installation","level":2,"title":"Installation","text":"Install uv with our official standalone installer:
macOS and LinuxWindows $ curl -LsSf https://astral.sh/uv/install.sh | sh\n
PS> powershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n
Then, check out the first steps or read on for a brief overview.
Tip
uv may also be installed with pip, Homebrew, and more. See all of the methods on the installation page.
","path":["uv"],"tags":[]},{"location":"#projects","level":2,"title":"Projects","text":"uv manages project dependencies and environments, with support for lockfiles, workspaces, and more, similar to rye or poetry:
$ uv init example\nInitialized project `example` at `/home/user/example`\n\n$ cd example\n\n$ uv add ruff\nCreating virtual environment at: .venv\nResolved 2 packages in 170ms\n Built example @ file:///home/user/example\nPrepared 2 packages in 627ms\nInstalled 2 packages in 1ms\n + example==0.1.0 (from file:///home/user/example)\n + ruff==0.5.4\n\n$ uv run ruff check\nAll checks passed!\n\n$ uv lock\nResolved 2 packages in 0.33ms\n\n$ uv sync\nResolved 2 packages in 0.70ms\nAudited 1 package in 0.02ms\n
See the project guide to get started.
uv also supports building and publishing projects, even if they're not managed with uv. See the packaging guide to learn more.
","path":["uv"],"tags":[]},{"location":"#scripts","level":2,"title":"Scripts","text":"uv manages dependencies and environments for single-file scripts.
Create a new script and add inline metadata declaring its dependencies:
$ echo 'import requests; print(requests.get(\"https://astral.sh\"))' > example.py\n\n$ uv add --script example.py requests\nUpdated `example.py`\n
Then, run the script in an isolated virtual environment:
$ uv run example.py\nReading inline script metadata from: example.py\nInstalled 5 packages in 12ms\n<Response [200]>\n
See the scripts guide to get started.
","path":["uv"],"tags":[]},{"location":"#tools","level":2,"title":"Tools","text":"uv executes and installs command-line tools provided by Python packages, similar to pipx.
Run a tool in an ephemeral environment using uvx (an alias for uv tool run):
$ uvx pycowsay 'hello world!'\nResolved 1 package in 167ms\nInstalled 1 package in 9ms\n + pycowsay==0.0.0.2\n \"\"\"\n\n ------------\n< hello world! >\n ------------\n \\ ^__^\n \\ (oo)\\_______\n (__)\\ )\\/\\\n ||----w |\n || ||\n
Install a tool with uv tool install:
$ uv tool install ruff\nResolved 1 package in 6ms\nInstalled 1 package in 2ms\n + ruff==0.5.4\nInstalled 1 executable: ruff\n\n$ ruff --version\nruff 0.5.4\n
See the tools guide to get started.
","path":["uv"],"tags":[]},{"location":"#python-versions","level":2,"title":"Python versions","text":"uv installs Python and allows quickly switching between versions.
Install multiple Python versions:
$ uv python install 3.10 3.11 3.12\nSearching for Python versions matching: Python 3.10\nSearching for Python versions matching: Python 3.11\nSearching for Python versions matching: Python 3.12\nInstalled 3 versions in 3.42s\n + cpython-3.10.14-macos-aarch64-none\n + cpython-3.11.9-macos-aarch64-none\n + cpython-3.12.4-macos-aarch64-none\n
Download Python versions as needed:
$ uv venv --python 3.12.0\nUsing CPython 3.12.0\nCreating virtual environment at: .venv\nActivate with: source .venv/bin/activate\n\n$ uv run --python pypy@3.8 -- python\nPython 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30)\n[PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin\nType \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n>>>>\n
Use a specific Python version in the current directory:
$ uv python pin 3.11\nPinned `.python-version` to `3.11`\n
See the installing Python guide to get started.
","path":["uv"],"tags":[]},{"location":"#the-pip-interface","level":2,"title":"The pip interface","text":"uv provides a drop-in replacement for common pip, pip-tools, and virtualenv commands.
uv extends their interfaces with advanced features, such as dependency version overrides, platform-independent resolutions, reproducible resolutions, alternative resolution strategies, and more.
Migrate to uv without changing your existing workflows — and experience a 10-100x speedup — with the uv pip interface.
Compile requirements into a platform-independent requirements file:
$ uv pip compile docs/requirements.in \\\n --universal \\\n --output-file docs/requirements.txt\nResolved 43 packages in 12ms\n
Create a virtual environment:
$ uv venv\nUsing CPython 3.12.3\nCreating virtual environment at: .venv\nActivate with: source .venv/bin/activate\n
Install the locked requirements:
$ uv pip sync docs/requirements.txt\nResolved 43 packages in 11ms\nInstalled 43 packages in 208ms\n + babel==2.15.0\n + black==24.4.2\n + certifi==2024.7.4\n ...\n
See the pip interface documentation to get started.
","path":["uv"],"tags":[]},{"location":"#learn-more","level":2,"title":"Learn more","text":"See the first steps or jump straight to the guides to start using uv.
","path":["uv"],"tags":[]},{"location":"concepts/","level":1,"title":"Concepts overview","text":"Read the concept documents to learn more about uv's features:
- Projects
- Tools
- Python versions
- Configuration files
- Package indexes
- Resolution
- The uv build backend
- Authentication
- Caching
- The pip interface
Looking for a quick introduction to features? See the guides instead.
","path":["Concepts","Concepts overview"],"tags":[]},{"location":"concepts/build-backend/","level":1,"title":"The uv build backend","text":"A build backend transforms a source tree (i.e., a directory) into a source distribution or a wheel.
uv supports all build backends (as specified by PEP 517), but also provides a native build backend (uv_build) that integrates tightly with uv to improve performance and user experience.
","path":["Concepts","The uv build backend"],"tags":[]},{"location":"concepts/build-backend/#choosing-a-build-backend","level":2,"title":"Choosing a build backend","text":"The uv build backend is a great choice for most Python projects. It has reasonable defaults, with the goal of requiring zero configuration for most users, but provides flexible configuration to accommodate most Python project structures. It integrates tightly with uv, to improve messaging and user experience. It validates project metadata and structures, preventing common mistakes. And, finally, it's very fast.
The uv build backend currently only supports pure Python code. An alternative backend is required to build a library with extension modules.
Tip
While the backend supports a number of options for configuring your project structure, when build scripts or a more flexible project layout are required, consider using the hatchling build backend instead.
","path":["Concepts","The uv build backend"],"tags":[]},{"location":"concepts/build-backend/#using-the-uv-build-backend","level":2,"title":"Using the uv build backend","text":"To use uv as a build backend in an existing project, add uv_build to the [build-system] section in your pyproject.toml:
pyproject.toml[build-system]\nrequires = [\"uv_build>=0.9.8,<0.10.0\"]\nbuild-backend = \"uv_build\"\n
Note
The uv build backend follows the same versioning policy as uv. Including an upper bound on the uv_build version ensures that your package continues to build correctly as new versions are released.
To create a new project that uses the uv build backend, use uv init:
$ uv init\n
When the project is built, e.g., with uv build, the uv build backend will be used to create the source distribution and wheel.
","path":["Concepts","The uv build backend"],"tags":[]},{"location":"concepts/build-backend/#bundled-build-backend","level":2,"title":"Bundled build backend","text":"The build backend is published as a separate package (uv_build) that is optimized for portability and small binary size. However, the uv executable also includes a copy of the build backend, which will be used during builds performed by uv, e.g., during uv build, if its version is compatible with the uv_build requirement. If it's not compatible, a compatible version of the uv_build package will be used. Other build frontends, such as python -m build, will always use the uv_build package, typically choosing the latest compatible version.
","path":["Concepts","The uv build backend"],"tags":[]},{"location":"concepts/build-backend/#modules","level":2,"title":"Modules","text":"Python packages are expected to contain one or more Python modules, which are directories containing an __init__.py. By default, a single root module is expected at src/<package_name>/__init__.py.
For example, the structure for a project named foo would be:
pyproject.toml\nsrc\n└── foo\n └── __init__.py\n
uv normalizes the package name to determine the default module name: the package name is lowercased and dots and dashes are replaced with underscores, e.g., Foo-Bar would be converted to foo_bar.
The src/ directory is the default directory for module discovery.
These defaults can be changed with the module-name and module-root settings. For example, to use a FOO module in the root directory, as in the project structure:
pyproject.toml\nFOO\n└── __init__.py\n
The correct build configuration would be:
pyproject.toml[tool.uv.build-backend]\nmodule-name = \"FOO\"\nmodule-root = \"\"\n
","path":["Concepts","The uv build backend"],"tags":[]},{"location":"concepts/build-backend/#namespace-packages","level":2,"title":"Namespace packages","text":"Namespace packages are intended for use-cases where multiple packages write modules into a shared namespace.
Namespace package modules are identified by a . in the module-name. For example, to package the module bar in the shared namespace foo, the project structure would be:
pyproject.toml\nsrc\n└── foo\n └── bar\n └── __init__.py\n
And the module-name configuration would be:
pyproject.toml[tool.uv.build-backend]\nmodule-name = \"foo.bar\"\n
Important
The __init__.py file is not included in foo, since it's the shared namespace module.
It's also possible to have a complex namespace package with more than one root module, e.g., with the project structure:
pyproject.toml\nsrc\n├── foo\n│ └── __init__.py\n└── bar\n └── __init__.py\n
While we do not recommend this structure (i.e., you should use a workspace with multiple packages instead), it is supported by setting module-name to a list of names:
pyproject.toml[tool.uv.build-backend]\nmodule-name = [\"foo\", \"bar\"]\n
For packages with many modules or complex namespaces, the namespace = true option can be used to avoid explicitly declaring each module name, e.g.:
pyproject.toml[tool.uv.build-backend]\nnamespace = true\n
Warning
Using namespace = true disables safety checks. Using an explicit list of module names is strongly recommended outside of legacy projects.
The namespace option can also be used with module-name to explicitly declare the root, e.g., for the project structure:
pyproject.toml\nsrc\n└── foo\n ├── bar\n │ └── __init__.py\n └── baz\n └── __init__.py\n
The recommended configuration would be:
pyproject.toml[tool.uv.build-backend]\nmodule-name = \"foo\"\nnamespace = true\n
","path":["Concepts","The uv build backend"],"tags":[]},{"location":"concepts/build-backend/#stub-packages","level":2,"title":"Stub packages","text":"The build backend also supports building type stub packages, which are identified by the -stubs suffix on the package or module name, e.g., foo-stubs. The module name for type stub packages must end in -stubs, so uv will not normalize the - to an underscore. Additionally, uv will search for a __init__.pyi file. For example, the project structure would be:
pyproject.toml\nsrc\n└── foo-stubs\n └── __init__.pyi\n
Type stub modules are also supported for namespace packages.
","path":["Concepts","The uv build backend"],"tags":[]},{"location":"concepts/build-backend/#file-inclusion-and-exclusion","level":2,"title":"File inclusion and exclusion","text":"The build backend is responsible for determining which files in a source tree should be packaged into the distributions.
To determine which files to include in a source distribution, uv first adds the included files and directories, then removes the excluded files and directories. This means that exclusions always take precedence over inclusions.
By default, uv excludes __pycache__, *.pyc, and *.pyo.
When building a source distribution, the following files and directories are included:
- The
pyproject.toml - The module under
tool.uv.build-backend.module-root. - The files referenced by
project.license-files and project.readme. - All directories under
tool.uv.build-backend.data. - All files matching patterns from
tool.uv.build-backend.source-include.
From these, items matching tool.uv.build-backend.source-exclude and the default excludes are removed.
When building a wheel, the following files and directories are included:
- The module under
tool.uv.build-backend.module-root - The files referenced by
project.license-files, which are copied into the .dist-info directory. - The
project.readme, which is copied into the project metadata. - All directories under
tool.uv.build-backend.data, which are copied into the .data directory.
From these, tool.uv.build-backend.source-exclude, tool.uv.build-backend.wheel-exclude and the default excludes are removed. The source dist excludes are applied to avoid source tree to wheel source builds including more files than source tree to source distribution to wheel build.
There are no specific wheel includes. There must only be one top level module, and all data files must either be under the module root or in the appropriate data directory. Most packages store small data in the module root alongside the source code.
Tip
When using the uv build backend through a frontend that is not uv, such as pip or python -m build, debug logging can be enabled through environment variables with RUST_LOG=uv=debug or RUST_LOG=uv=verbose. When used through uv, the uv build backend shares the verbosity level of uv.
","path":["Concepts","The uv build backend"],"tags":[]},{"location":"concepts/build-backend/#include-and-exclude-syntax","level":3,"title":"Include and exclude syntax","text":"Includes are anchored, which means that pyproject.toml includes only <root>/pyproject.toml and not <root>/bar/pyproject.toml. To recursively include all files under a directory, use a /** suffix, e.g. src/**. Recursive inclusions are also anchored, e.g., assets/**/sample.csv includes all sample.csv files in <root>/assets or any of its children.
Note
For performance and reproducibility, avoid patterns without an anchor such as **/sample.csv.
Excludes are not anchored, which means that __pycache__ excludes all directories named __pycache__ regardless of its parent directory. All children of an exclusion are excluded as well. To anchor a directory, use a / prefix, e.g., /dist will exclude only <root>/dist.
All fields accepting patterns use the reduced portable glob syntax from PEP 639, with the addition that characters can be escaped with a backslash.
","path":["Concepts","The uv build backend"],"tags":[]},{"location":"concepts/cache/","level":1,"title":"Caching","text":"","path":["Concepts","Caching"],"tags":[]},{"location":"concepts/cache/#dependency-caching","level":2,"title":"Dependency caching","text":"uv uses aggressive caching to avoid re-downloading (and re-building) dependencies that have already been accessed in prior runs.
The specifics of uv's caching semantics vary based on the nature of the dependency:
- For registry dependencies (like those downloaded from PyPI), uv respects HTTP caching headers.
- For direct URL dependencies, uv respects HTTP caching headers, and also caches based on the URL itself.
- For Git dependencies, uv caches based on the fully-resolved Git commit hash. As such,
uv pip compile will pin Git dependencies to a specific commit hash when writing the resolved dependency set. - For local dependencies, uv caches based on the last-modified time of the source archive (i.e., the local
.whl or .tar.gz file). For directories, uv caches based on the last-modified time of the pyproject.toml, setup.py, or setup.cfg file.
If you're running into caching issues, uv includes a few escape hatches:
- To clear the cache entirely, run
uv cache clean. To clear the cache for a specific package, run uv cache clean <package-name>. For example, uv cache clean ruff will clear the cache for the ruff package. - To force uv to revalidate cached data for all dependencies, pass
--refresh to any command (e.g., uv sync --refresh or uv pip install --refresh ...). - To force uv to revalidate cached data for a specific dependency pass
--refresh-package to any command (e.g., uv sync --refresh-package ruff or uv pip install --refresh-package ruff ...). - To force uv to ignore existing installed versions, pass
--reinstall to any installation command (e.g., uv sync --reinstall or uv pip install --reinstall ...). (Consider running uv cache clean <package-name> first, to ensure that the cache is cleared prior to reinstallation.)
As a special case, uv will always rebuild and reinstall any local directory dependencies passed explicitly on the command-line (e.g., uv pip install .).
","path":["Concepts","Caching"],"tags":[]},{"location":"concepts/cache/#dynamic-metadata","level":2,"title":"Dynamic metadata","text":"By default, uv will only rebuild and reinstall local directory dependencies (e.g., editables) if the pyproject.toml, setup.py, or setup.cfg file in the directory root has changed, or if a src directory is added or removed. This is a heuristic and, in some cases, may lead to fewer re-installs than desired.
To incorporate additional information into the cache key for a given package, you can add cache key entries under tool.uv.cache-keys, which covers both file paths and Git commit hashes. Setting tool.uv.cache-keys will replace defaults, so any necessary files (like pyproject.toml) should still be included in the user-defined cache keys.
For example, if a project specifies dependencies in pyproject.toml but uses setuptools-scm to manage its version, and should thus be rebuilt whenever the commit hash or dependencies change, you can add the following to the project's pyproject.toml:
pyproject.toml[tool.uv]\ncache-keys = [{ file = \"pyproject.toml\" }, { git = { commit = true } }]\n
If your dynamic metadata incorporates information from the set of Git tags, you can expand the cache key to include the tags:
pyproject.toml[tool.uv]\ncache-keys = [{ file = \"pyproject.toml\" }, { git = { commit = true, tags = true } }]\n
Similarly, if a project reads from a requirements.txt to populate its dependencies, you can add the following to the project's pyproject.toml:
pyproject.toml[tool.uv]\ncache-keys = [{ file = \"pyproject.toml\" }, { file = \"requirements.txt\" }]\n
Globs are supported for file keys, following the syntax of the glob crate. For example, to invalidate the cache whenever a .toml file in the project directory or any of its subdirectories is modified, use the following:
pyproject.toml[tool.uv]\ncache-keys = [{ file = \"**/*.toml\" }]\n
Note
The use of globs can be expensive, as uv may need to walk the filesystem to determine whether any files have changed. This may, in turn, requiring traversal of large or deeply nested directories.
Similarly, if a project relies on an environment variable, you can add the following to the project's pyproject.toml to invalidate the cache whenever the environment variable changes:
pyproject.toml[tool.uv]\ncache-keys = [{ file = \"pyproject.toml\" }, { env = \"MY_ENV_VAR\" }]\n
Finally, to invalidate a project whenever a specific directory (like src) is created or removed, add the following to the project's pyproject.toml:
pyproject.toml[tool.uv]\ncache-keys = [{ file = \"pyproject.toml\" }, { dir = \"src\" }]\n
Note that the dir key will only track changes to the directory itself, and not arbitrary changes within the directory.
As an escape hatch, if a project uses dynamic metadata that isn't covered by tool.uv.cache-keys, you can instruct uv to always rebuild and reinstall it by adding the project to the tool.uv.reinstall-package list:
pyproject.toml[tool.uv]\nreinstall-package = [\"my-package\"]\n
This will force uv to rebuild and reinstall my-package on every run, regardless of whether the package's pyproject.toml, setup.py, or setup.cfg file has changed.
","path":["Concepts","Caching"],"tags":[]},{"location":"concepts/cache/#cache-safety","level":2,"title":"Cache safety","text":"It's safe to run multiple uv commands concurrently, even against the same virtual environment. uv's cache is designed to be thread-safe and append-only, and thus robust to multiple concurrent readers and writers. uv applies a file-based lock to the target virtual environment when installing, to avoid concurrent modifications across processes.
Note that it's not safe to modify the uv cache (e.g., uv cache clean) while other uv commands are running, and never safe to modify the cache directly (e.g., by removing a file or directory).
","path":["Concepts","Caching"],"tags":[]},{"location":"concepts/cache/#clearing-the-cache","level":2,"title":"Clearing the cache","text":"uv provides a few different mechanisms for removing entries from the cache:
uv cache clean removes all cache entries from the cache directory, clearing it out entirely.uv cache clean ruff removes all cache entries for the ruff package, useful for invalidating the cache for a single or finite set of packages.uv cache prune removes all unused cache entries. For example, the cache directory may contain entries created in previous uv versions that are no longer necessary and can be safely removed. uv cache prune is safe to run periodically, to keep the cache directory clean.
","path":["Concepts","Caching"],"tags":[]},{"location":"concepts/cache/#caching-in-continuous-integration","level":2,"title":"Caching in continuous integration","text":"It's common to cache package installation artifacts in continuous integration environments (like GitHub Actions or GitLab CI) to speed up subsequent runs.
By default, uv caches both the wheels that it builds from source and the pre-built wheels that it downloads directly, to enable high-performance package installation.
However, in continuous integration environments, persisting pre-built wheels may be undesirable. With uv, it turns out that it's often faster to omit pre-built wheels from the cache (and instead re-download them from the registry on each run). On the other hand, caching wheels that are built from source tends to be worthwhile, since the wheel building process can be expensive, especially for extension modules.
To support this caching strategy, uv provides a uv cache prune --ci command, which removes all pre-built wheels and unzipped source distributions from the cache, but retains any wheels that were built from source. We recommend running uv cache prune --ci at the end of your continuous integration job to ensure maximum cache efficiency. For an example, see the GitHub integration guide.
","path":["Concepts","Caching"],"tags":[]},{"location":"concepts/cache/#cache-directory","level":2,"title":"Cache directory","text":"uv determines the cache directory according to, in order:
- A temporary cache directory, if
--no-cache was requested. - The specific cache directory specified via
--cache-dir, UV_CACHE_DIR, or tool.uv.cache-dir. - A system-appropriate cache directory, e.g.,
$XDG_CACHE_HOME/uv or $HOME/.cache/uv on Unix and %LOCALAPPDATA%\\uv\\cache on Windows
Note
uv always requires a cache directory. When --no-cache is requested, uv will still use a temporary cache for sharing data within that single invocation.
In most cases, --refresh should be used instead of --no-cache — as it will update the cache for subsequent operations but not read from the cache.
It is important for performance for the cache directory to be located on the same file system as the Python environment uv is operating on. Otherwise, uv will not be able to link files from the cache into the environment and will instead need to fallback to slow copy operations.
","path":["Concepts","Caching"],"tags":[]},{"location":"concepts/cache/#cache-versioning","level":2,"title":"Cache versioning","text":"The uv cache is composed of a number of buckets (e.g., a bucket for wheels, a bucket for source distributions, a bucket for Git repositories, and so on). Each bucket is versioned, such that if a release contains a breaking change to the cache format, uv will not attempt to read from or write to an incompatible cache bucket.
For example, uv 0.4.13 included a breaking change to the core metadata bucket. As such, the bucket version was increased from v12 to v13. Within a cache version, changes are guaranteed to be both forwards- and backwards-compatible.
Since changes in the cache format are accompanied by changes in the cache version, multiple versions of uv can safely read and write to the same cache directory. However, if the cache version changed between a given pair of uv releases, then those releases may not be able to share the same underlying cache entries.
For example, it's safe to use a single shared cache for uv 0.4.12 and uv 0.4.13, though the cache itself may contain duplicate entries in the core metadata bucket due to the change in cache version.
","path":["Concepts","Caching"],"tags":[]},{"location":"concepts/configuration-files/","level":1,"title":"Configuration files","text":"uv supports persistent configuration files at both the project- and user-level.
Specifically, uv will search for a pyproject.toml or uv.toml file in the current directory, or in the nearest parent directory.
Note
For tool commands, which operate at the user level, local configuration files will be ignored. Instead, uv will exclusively read from user-level configuration (e.g., ~/.config/uv/uv.toml) and system-level configuration (e.g., /etc/uv/uv.toml).
In workspaces, uv will begin its search at the workspace root, ignoring any configuration defined in workspace members. Since the workspace is locked as a single unit, configuration is shared across all members.
If a pyproject.toml file is found, uv will read configuration from the [tool.uv] table. For example, to set a persistent index URL, add the following to a pyproject.toml:
pyproject.toml[[tool.uv.index]]\nurl = \"https://test.pypi.org/simple\"\ndefault = true\n
(If there is no such table, the pyproject.toml file will be ignored, and uv will continue searching in the directory hierarchy.)
uv will also search for uv.toml files, which follow an identical structure, but omit the [tool.uv] prefix. For example:
uv.toml[[index]]\nurl = \"https://test.pypi.org/simple\"\ndefault = true\n
Note
uv.toml files take precedence over pyproject.toml files, so if both uv.toml and pyproject.toml files are present in a directory, configuration will be read from uv.toml, and [tool.uv] section in the accompanying pyproject.toml will be ignored.
uv will also discover user-level configuration at ~/.config/uv/uv.toml (or $XDG_CONFIG_HOME/uv/uv.toml) on macOS and Linux, or %APPDATA%\\uv\\uv.toml on Windows; and system-level configuration at /etc/uv/uv.toml (or $XDG_CONFIG_DIRS/uv/uv.toml) on macOS and Linux, or %SYSTEMDRIVE%\\ProgramData\\uv\\uv.toml on Windows.
User-and system-level configuration must use the uv.toml format, rather than the pyproject.toml format, as a pyproject.toml is intended to define a Python project.
If project-, user-, and system-level configuration files are found, the settings will be merged, with project-level configuration taking precedence over the user-level configuration, and user-level configuration taking precedence over the system-level configuration. (If multiple system-level configuration files are found, e.g., at both /etc/uv/uv.toml and $XDG_CONFIG_DIRS/uv/uv.toml, only the first-discovered file will be used, with XDG taking priority.)
For example, if a string, number, or boolean is present in both the project- and user-level configuration tables, the project-level value will be used, and the user-level value will be ignored. If an array is present in both tables, the arrays will be concatenated, with the project-level settings appearing earlier in the merged array.
Settings provided via environment variables take precedence over persistent configuration, and settings provided via the command line take precedence over both.
uv accepts a --no-config command-line argument which, when provided, disables the discovery of any persistent configuration.
uv also accepts a --config-file command-line argument, which accepts a path to a uv.toml to use as the configuration file. When provided, this file will be used in place of any discovered configuration files (e.g., user-level configuration will be ignored).
","path":["Concepts","Configuration files"],"tags":[]},{"location":"concepts/configuration-files/#settings","level":2,"title":"Settings","text":"See the settings reference for an enumeration of the available settings.
","path":["Concepts","Configuration files"],"tags":[]},{"location":"concepts/configuration-files/#env","level":2,"title":".env","text":"uv run can load environment variables from dotenv files (e.g., .env, .env.local, .env.development), powered by the dotenvy crate.
To load a .env file from a dedicated location, set the UV_ENV_FILE environment variable, or pass the --env-file flag to uv run.
For example, to load environment variables from a .env file in the current working directory:
$ echo \"MY_VAR='Hello, world!'\" > .env\n$ uv run --env-file .env -- python -c 'import os; print(os.getenv(\"MY_VAR\"))'\nHello, world!\n
The --env-file flag can be provided multiple times, with subsequent files overriding values defined in previous files. To provide multiple files via the UV_ENV_FILE environment variable, separate the paths with a space (e.g., UV_ENV_FILE=\"/path/to/file1 /path/to/file2\").
To disable dotenv loading (e.g., to override UV_ENV_FILE or the --env-file command-line argument), set the UV_NO_ENV_FILE environment variable to 1, or pass the--no-env-file flag to uv run.
If the same variable is defined in the environment and in a .env file, the value from the environment will take precedence.
","path":["Concepts","Configuration files"],"tags":[]},{"location":"concepts/configuration-files/#configuring-the-pip-interface","level":2,"title":"Configuring the pip interface","text":"A dedicated [tool.uv.pip] section is provided for configuring just the uv pip command line interface. Settings in this section will not apply to uv commands outside the uv pip namespace. However, many of the settings in this section have corollaries in the top-level namespace which do apply to the uv pip interface unless they are overridden by a value in the uv.pip section.
The uv.pip settings are designed to adhere closely to pip's interface and are declared separately to retain compatibility while allowing the global settings to use alternate designs (e.g., --no-build).
As an example, setting the index-url under [tool.uv.pip], as in the following pyproject.toml, would only affect the uv pip subcommands (e.g., uv pip install, but not uv sync, uv lock, or uv run):
pyproject.toml[tool.uv.pip]\nindex-url = \"https://test.pypi.org/simple\"\n
","path":["Concepts","Configuration files"],"tags":[]},{"location":"concepts/indexes/","level":1,"title":"Package indexes","text":"By default, uv uses the Python Package Index (PyPI) for dependency resolution and package installation. However, uv can be configured to use other package indexes, including private indexes, via the [[tool.uv.index]] configuration option (and --index, the analogous command-line option).
","path":["Concepts","Package indexes"],"tags":[]},{"location":"concepts/indexes/#defining-an-index","level":2,"title":"Defining an index","text":"To include an additional index when resolving dependencies, add a [[tool.uv.index]] entry to your pyproject.toml:
[[tool.uv.index]]\n# Optional name for the index.\nname = \"pytorch\"\n# Required URL for the index.\nurl = \"https://download.pytorch.org/whl/cpu\"\n
Indexes are prioritized in the order in which they’re defined, such that the first index listed in the configuration file is the first index consulted when resolving dependencies, with indexes provided via the command line taking precedence over those in the configuration file.
By default, uv includes the Python Package Index (PyPI) as the \"default\" index, i.e., the index used when a package is not found on any other index. To exclude PyPI from the list of indexes, set default = true on another index entry (or use the --default-index command-line option):
[[tool.uv.index]]\nname = \"pytorch\"\nurl = \"https://download.pytorch.org/whl/cpu\"\ndefault = true\n
The default index is always treated as lowest priority, regardless of its position in the list of indexes.
Index names may only contain alphanumeric characters, dashes, underscores, and periods, and must be valid ASCII.
When providing an index on the command line (with --index or --default-index) or through an environment variable (UV_INDEX or UV_DEFAULT_INDEX), names are optional but can be included using the <name>=<url> syntax, as in:
# On the command line.\n$ uv lock --index pytorch=https://download.pytorch.org/whl/cpu\n# Via an environment variable.\n$ UV_INDEX=pytorch=https://download.pytorch.org/whl/cpu uv lock\n
","path":["Concepts","Package indexes"],"tags":[]},{"location":"concepts/indexes/#pinning-a-package-to-an-index","level":2,"title":"Pinning a package to an index","text":"A package can be pinned to a specific index by specifying the index in its tool.uv.sources entry. For example, to ensure that torch is always installed from the pytorch index, add the following to your pyproject.toml:
[tool.uv.sources]\ntorch = { index = \"pytorch\" }\n\n[[tool.uv.index]]\nname = \"pytorch\"\nurl = \"https://download.pytorch.org/whl/cpu\"\n
Similarly, to pull from a different index based on the platform, you can provide a list of sources disambiguated by environment markers:
pyproject.toml[project]\ndependencies = [\"torch\"]\n\n[tool.uv.sources]\ntorch = [\n { index = \"pytorch-cu118\", marker = \"sys_platform == 'darwin'\"},\n { index = \"pytorch-cu124\", marker = \"sys_platform != 'darwin'\"},\n]\n\n[[tool.uv.index]]\nname = \"pytorch-cu118\"\nurl = \"https://download.pytorch.org/whl/cu118\"\n\n[[tool.uv.index]]\nname = \"pytorch-cu124\"\nurl = \"https://download.pytorch.org/whl/cu124\"\n
An index can be marked as explicit = true to prevent packages from being installed from that index unless explicitly pinned to it. For example, to ensure that torch is installed from the pytorch index, but all other packages are installed from PyPI, add the following to your pyproject.toml:
[tool.uv.sources]\ntorch = { index = \"pytorch\" }\n\n[[tool.uv.index]]\nname = \"pytorch\"\nurl = \"https://download.pytorch.org/whl/cpu\"\nexplicit = true\n
Named indexes referenced via tool.uv.sources must be defined within the project's pyproject.toml file; indexes provided via the command-line, environment variables, or user-level configuration will not be recognized.
If an index is marked as both default = true and explicit = true, it will be treated as an explicit index (i.e., only usable via tool.uv.sources) while also removing PyPI as the default index.
","path":["Concepts","Package indexes"],"tags":[]},{"location":"concepts/indexes/#searching-across-multiple-indexes","level":2,"title":"Searching across multiple indexes","text":"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).
For example, if an internal index is specified via [[tool.uv.index]], uv's behavior is such that if a package exists on that internal index, it will always be installed from that internal index, and never from PyPI. The intent is to prevent \"dependency confusion\" attacks, in which an attacker publishes a malicious package on PyPI with the same name as an internal package, thus causing the malicious package to be installed instead of the internal package. See, for example, the torchtriton attack from December 2022.
To opt in to alternate index behaviors, use the--index-strategy command-line option, or the UV_INDEX_STRATEGY environment variable, which supports the following values:
first-index (default): Search for each package across all indexes, limiting the candidate versions to those present in the first index that contains the package.unsafe-first-match: Search for each package across all indexes, but prefer the first index with a compatible version, even if newer versions are available on other indexes.unsafe-best-match: Search for each package across all indexes, and select the best version from the combined set of candidate versions.
While unsafe-best-match is the closest to pip's behavior, it exposes users to the risk of \"dependency confusion\" attacks.
","path":["Concepts","Package indexes"],"tags":[]},{"location":"concepts/indexes/#authentication","level":2,"title":"Authentication","text":"Most private package indexes require authentication to access packages, typically via a username and password (or access token).
Tip
See the alternative index guide for details on authenticating with specific private index providers, e.g., from AWS, Azure, or GCP.
","path":["Concepts","Package indexes"],"tags":[]},{"location":"concepts/indexes/#providing-credentials-directly","level":3,"title":"Providing credentials directly","text":"Credentials can be provided directly via environment variables or by embedding them in the URL.
For example, given an index named internal-proxy that requires a username (public) and password (koala), define the index (without credentials) in your pyproject.toml:
[[tool.uv.index]]\nname = \"internal-proxy\"\nurl = \"https://example.com/simple\"\n
From there, you can set the UV_INDEX_INTERNAL_PROXY_USERNAME and UV_INDEX_INTERNAL_PROXY_PASSWORD environment variables, where INTERNAL_PROXY is the uppercase version of the index name, with non-alphanumeric characters replaced by underscores:
export UV_INDEX_INTERNAL_PROXY_USERNAME=public\nexport UV_INDEX_INTERNAL_PROXY_PASSWORD=koala\n
By providing credentials via environment variables, you can avoid storing sensitive information in the plaintext pyproject.toml file.
Alternatively, credentials can be embedded directly in the index definition:
[[tool.uv.index]]\nname = \"internal\"\nurl = \"https://public:koala@pypi-proxy.corp.dev/simple\"\n
For security purposes, credentials are never stored in the uv.lock file; as such, uv must have access to the authenticated URL at installation time.
","path":["Concepts","Package indexes"],"tags":[]},{"location":"concepts/indexes/#using-credential-providers","level":3,"title":"Using credential providers","text":"In addition to providing credentials directly, uv supports discovery of credentials from netrc and keyring. See the HTTP authentication documentation for details on setting up specific credential providers.
By default, uv will attempt an unauthenticated request before querying providers. If the request fails, uv will search for credentials. If credentials are found, an authenticated request will be attempted.
Note
If a username is set, uv will search for credentials before making an unauthenticated request.
Some indexes (e.g., GitLab) will forward unauthenticated requests to a public index, like PyPI — which means that uv will not search for credentials. This behavior can be changed per-index, using the authenticate setting. For example, to always search for credentials:
[[tool.uv.index]]\nname = \"example\"\nurl = \"https://example.com/simple\"\nauthenticate = \"always\"\n
When authenticate is set to always, uv will eagerly search for credentials and error if credentials cannot be found.
","path":["Concepts","Package indexes"],"tags":[]},{"location":"concepts/indexes/#ignoring-error-codes-when-searching-across-indexes","level":3,"title":"Ignoring error codes when searching across indexes","text":"When using the first-index strategy, uv will stop searching across indexes if an HTTP 401 Unauthorized or HTTP 403 Forbidden status code is encountered. The one exception is that uv will ignore 403s when searching the pytorch index (since this index returns a 403 when a package is not present).
To configure which error codes are ignored for an index, use the ignored-error-codes setting. For example, to ignore 403s (but not 401s) for a private index:
[[tool.uv.index]]\nname = \"private-index\"\nurl = \"https://private-index.com/simple\"\nauthenticate = \"always\"\nignore-error-codes = [403]\n
uv will always continue searching across indexes when it encounters a 404 Not Found. This cannot be overridden.
","path":["Concepts","Package indexes"],"tags":[]},{"location":"concepts/indexes/#disabling-authentication","level":3,"title":"Disabling authentication","text":"To prevent leaking credentials, authentication can be disabled for an index:
[[tool.uv.index]]\nname = \"example\"\nurl = \"https://example.com/simple\"\nauthenticate = \"never\"\n
When authenticate is set to never, uv will never search for credentials for the given index and will error if credentials are provided directly.
","path":["Concepts","Package indexes"],"tags":[]},{"location":"concepts/indexes/#customizing-cache-control-headers","level":3,"title":"Customizing cache control headers","text":"By default, uv will respect the cache control headers provided by the index. For example, PyPI serves package metadata with a max-age=600 header, thereby allowing uv to cache package metadata for 10 minutes; and wheels and source distributions with a max-age=365000000, immutable header, thereby allowing uv to cache artifacts indefinitely.
To override the cache control headers for an index, use the cache-control setting:
[[tool.uv.index]]\nname = \"example\"\nurl = \"https://example.com/simple\"\ncache-control = { api = \"max-age=600\", files = \"max-age=365000000, immutable\" }\n
The cache-control setting accepts an object with two optional keys:
api: Controls caching for Simple API requests (package metadata).files: Controls caching for artifact downloads (wheels and source distributions).
The values for these keys are strings that follow the HTTP Cache-Control syntax. For example, to force uv to always revalidate package metadata, set api = \"no-cache\":
[[tool.uv.index]]\nname = \"example\"\nurl = \"https://example.com/simple\"\ncache-control = { api = \"no-cache\" }\n
This setting is most commonly used to override the default cache control headers for private indexes that otherwise disable caching, often unintentionally. We typically recommend following PyPI's approach to caching headers, i.e., setting api = \"max-age=600\" and files = \"max-age=365000000, immutable\".
","path":["Concepts","Package indexes"],"tags":[]},{"location":"concepts/indexes/#flat-indexes","level":2,"title":"\"Flat\" indexes","text":"By default, [[tool.uv.index]] entries are assumed to be PyPI-style registries that implement the PEP 503 Simple Repository API. However, uv also supports \"flat\" indexes, which are local directories or HTML pages that contain flat lists of wheels and source distributions. In pip, such indexes are specified using the --find-links option.
To define a flat index in your pyproject.toml, use the format = \"flat\" option:
[[tool.uv.index]]\nname = \"example\"\nurl = \"/path/to/directory\"\nformat = \"flat\"\n
Flat indexes support the same feature set as Simple Repository API indexes (e.g., explicit = true); you can also pin a package to a flat index using tool.uv.sources.
","path":["Concepts","Package indexes"],"tags":[]},{"location":"concepts/indexes/#-index-url-and-extra-index-url","level":2,"title":"--index-url and --extra-index-url","text":"In addition to the [[tool.uv.index]] configuration option, uv supports pip-style --index-url and --extra-index-url command-line options for compatibility, where --index-url defines the default index and --extra-index-url defines additional indexes.
These options can be used in conjunction with the [[tool.uv.index]] configuration option, and follow the same prioritization rules:
- The default index is always treated as lowest priority, whether defined via the legacy
--index-url argument, the recommended --default-index argument, or a [[tool.uv.index]] entry with default = true. - Indexes are consulted in the order in which they’re defined, either via the legacy
--extra-index-url argument, the recommended --index argument, or [[tool.uv.index]] entries.
In effect, --index-url and --extra-index-url can be thought of as unnamed [[tool.uv.index]] entries, with default = true enabled for the former. In that context, --index-url maps to --default-index, and --extra-index-url maps to --index.
","path":["Concepts","Package indexes"],"tags":[]},{"location":"concepts/preview/","level":1,"title":"Preview features","text":"uv includes opt-in preview features to provide an opportunity for community feedback and increase confidence that changes are a net-benefit before enabling them for everyone.
","path":["Concepts","Preview features"],"tags":[]},{"location":"concepts/preview/#enabling-preview-features","level":2,"title":"Enabling preview features","text":"To enable all preview features, use the --preview flag:
$ uv run --preview ...\n
Or, set the UV_PREVIEW environment variable:
$ UV_PREVIEW=1 uv run ...\n
To enable specific preview features, use the --preview-features flag:
$ uv run --preview-features foo ...\n
The --preview-features flag can be repeated to enable multiple features:
$ uv run --preview-features foo --preview-features bar ...\n
Or, features can be provided in a comma separated list:
$ uv run --preview-features foo,bar ...\n
The UV_PREVIEW_FEATURES environment variable can be used similarly, e.g.:
$ UV_PREVIEW_FEATURES=foo,bar uv run ...\n
For backwards compatibility, enabling preview features that do not exist will warn, but not error.
","path":["Concepts","Preview features"],"tags":[]},{"location":"concepts/preview/#using-preview-features","level":2,"title":"Using preview features","text":"Often, preview features can be used without changing any preview settings if the behavior change is gated by some sort of user interaction, For example, while pylock.toml support is in preview, you can use uv pip install with a pylock.toml file without additional configuration because specifying the pylock.toml file indicates you want to use the feature. However, a warning will be displayed that the feature is in preview. The preview feature can be enabled to silence the warning.
Other preview features change behavior without changes to your use of uv. For example, when the python-upgrade feature is enabled, the default behavior of uv python install changes to allow uv to upgrade Python versions transparently. This feature requires enabling the preview flag for proper usage.
","path":["Concepts","Preview features"],"tags":[]},{"location":"concepts/preview/#available-preview-features","level":2,"title":"Available preview features","text":"The following preview features are available:
add-bounds: Allows configuring the default bounds for uv add invocations.json-output: Allows --output-format json for various uv commands.package-conflicts: Allows defining workspace conflicts at the package level.pylock: Allows installing from pylock.toml files.python-install-default: Allows installing python and python3 executables.python-upgrade: Allows transparent Python version upgrades.format: Allows using uv format.native-auth: Enables storage of credentials in a system-native location.
","path":["Concepts","Preview features"],"tags":[]},{"location":"concepts/preview/#disabling-preview-features","level":2,"title":"Disabling preview features","text":"The --no-preview option can be used to disable preview features.
","path":["Concepts","Preview features"],"tags":[]},{"location":"concepts/python-versions/","level":1,"title":"Python versions","text":"A Python version is composed of a Python interpreter (i.e. the python executable), the standard library, and other supporting files.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#managed-and-system-python-installations","level":2,"title":"Managed and system Python installations","text":"Since it is common for a system to have an existing Python installation, uv supports discovering Python versions. However, uv also supports installing Python versions itself. To distinguish between these two types of Python installations, uv refers to Python versions it installs as managed Python installations and all other Python installations as system Python installations.
Note
uv does not distinguish between Python versions installed by the operating system vs those installed and managed by other tools. For example, if a Python installation is managed with pyenv, it would still be considered a system Python version in uv.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#requesting-a-version","level":2,"title":"Requesting a version","text":"A specific Python version can be requested with the --python flag in most uv commands. For example, when creating a virtual environment:
$ uv venv --python 3.11.6\n
uv will ensure that Python 3.11.6 is available — downloading and installing it if necessary — then create the virtual environment with it.
The following Python version request formats are supported:
<version> (e.g., 3, 3.12, 3.12.3)<version-specifier> (e.g., >=3.12,<3.13)<version><short-variant> (e.g., 3.13t, 3.12.0d)<version>+<variant> (e.g., 3.13+freethreaded, 3.12.0+debug)<implementation> (e.g., cpython or cp)<implementation>@<version> (e.g., cpython@3.12)<implementation><version> (e.g., cpython3.12 or cp312)<implementation><version-specifier> (e.g., cpython>=3.12,<3.13)<implementation>-<version>-<os>-<arch>-<libc> (e.g., cpython-3.12.3-macos-aarch64-none)
Additionally, a specific system Python interpreter can be requested with:
<executable-path> (e.g., /opt/homebrew/bin/python3)<executable-name> (e.g., mypython3)<install-dir> (e.g., /some/environment/)
By default, uv will automatically download Python versions if they cannot be found on the system. This behavior can be disabled with the python-downloads option.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#python-version-files","level":3,"title":"Python version files","text":"The .python-version file can be used to create a default Python version request. uv searches for a .python-version file in the working directory and each of its parents. If none is found, uv will check the user-level configuration directory. Any of the request formats described above can be used, though use of a version number is recommended for interoperability with other tools.
A .python-version file can be created in the current directory with the uv python pin command.
A global .python-version file can be created in the user configuration directory with the uv python pin --global command.
Discovery of .python-version files can be disabled with --no-config.
uv will not search for .python-version files beyond project or workspace boundaries (except the user configuration directory).
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#installing-a-python-version","level":2,"title":"Installing a Python version","text":"uv bundles a list of downloadable CPython and PyPy distributions for macOS, Linux, and Windows.
Tip
By default, Python versions are automatically downloaded as needed without using uv python install.
To install a Python version at a specific version:
$ uv python install 3.12.3\n
To install the latest patch version:
$ uv python install 3.12\n
To install a version that satisfies constraints:
$ uv python install '>=3.8,<3.10'\n
To install multiple versions:
$ uv python install 3.9 3.10 3.11\n
To install a specific implementation:
$ uv python install pypy\n
All the Python version request formats are supported except those that are used for requesting local interpreters such as a file path.
By default uv python install will verify that a managed Python version is installed or install the latest version. If a .python-version file is present, uv will install the Python version listed in the file. A project that requires multiple Python versions may define a .python-versions file. If present, uv will install all the Python versions listed in the file.
Important
The available Python versions are frozen for each uv release. To install new Python versions, you may need upgrade uv.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#installing-python-executables","level":3,"title":"Installing Python executables","text":"uv installs Python executables into your PATH by default, e.g., uv python install 3.12 will install a Python executable into ~/.local/bin, e.g., as python3.12.
Tip
If ~/.local/bin is not in your PATH, you can add it with uv tool update-shell.
To install python and python3 executables, include the experimental --default option:
$ uv python install 3.12 --default\n
When installing Python executables, uv will only overwrite an existing executable if it is managed by uv — e.g., if ~/.local/bin/python3.12 exists already uv will not overwrite it without the --force flag.
uv will update executables that it manages. However, it will prefer the latest patch version of each Python minor version by default. For example:
$ uv python install 3.12.7 # Adds `python3.12` to `~/.local/bin`\n$ uv python install 3.12.6 # Does not update `python3.12`\n$ uv python install 3.12.8 # Updates `python3.12` to point to 3.12.8\n
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#upgrading-python-versions","level":2,"title":"Upgrading Python versions","text":"Important
Support for upgrading Python versions is in preview. This means the behavior is experimental and subject to change.
Upgrades are only supported for uv-managed Python versions.
Upgrades are not currently supported for PyPy and GraalPy.
uv allows transparently upgrading Python versions to the latest patch release, e.g., 3.13.4 to 3.13.5. uv does not allow transparently upgrading across minor Python versions, e.g., 3.12 to 3.13, because changing minor versions can affect dependency resolution.
uv-managed Python versions can be upgraded to the latest supported patch release with the python upgrade command:
To upgrade a Python version to the latest supported patch release:
$ uv python upgrade 3.12\n
To upgrade all installed Python versions:
$ uv python upgrade\n
After an upgrade, uv will prefer the new version, but will retain the existing version as it may still be used by virtual environments.
If the Python version was installed with the python-upgrade preview feature enabled, e.g., uv python install 3.12 --preview-features python-upgrade, virtual environments using the Python version will be automatically upgraded to the new patch version.
Note
If the virtual environment was created before opting in to the preview mode, it will not be included in the automatic upgrades.
If a virtual environment was created with an explicitly requested patch version, e.g., uv venv -p 3.10.8, it will not be transparently upgraded to a new version.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#minor-version-directories","level":3,"title":"Minor version directories","text":"Automatic upgrades for virtual environments are implemented using a directory with the Python minor version, e.g.:
~/.local/share/uv/python/cpython-3.12-macos-aarch64-none\n
which is a symbolic link (on Unix) or junction (on Windows) pointing to a specific patch version:
$ readlink ~/.local/share/uv/python/cpython-3.12-macos-aarch64-none\n~/.local/share/uv/python/cpython-3.12.11-macos-aarch64-none\n
If this link is resolved by another tool, e.g., by canonicalizing the Python interpreter path, and used to create a virtual environment, it will not be automatically upgraded.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#project-python-versions","level":2,"title":"Project Python versions","text":"uv will respect Python requirements defined in requires-python in the pyproject.toml file during project command invocations. The first Python version that is compatible with the requirement will be used, unless a version is otherwise requested, e.g., via a .python-version file or the --python flag.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#viewing-available-python-versions","level":2,"title":"Viewing available Python versions","text":"To list installed and available Python versions:
$ uv python list\n
To filter the Python versions, provide a request, e.g., to show all Python 3.13 interpreters:
$ uv python list 3.13\n
Or, to show all PyPy interpreters:
$ uv python list pypy\n
By default, downloads for other platforms and old patch versions are hidden.
To view all versions:
$ uv python list --all-versions\n
To view Python versions for other platforms:
$ uv python list --all-platforms\n
To exclude downloads and only show installed Python versions:
$ uv python list --only-installed\n
See the uv python list reference for more details.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#finding-a-python-executable","level":2,"title":"Finding a Python executable","text":"To find a Python executable, use the uv python find command:
$ uv python find\n
By default, this will display the path to the first available Python executable. See the discovery rules for details about how executables are discovered.
This interface also supports many request formats, e.g., to find a Python executable that has a version of 3.11 or newer:
$ uv python find '>=3.11'\n
By default, uv python find will include Python versions from virtual environments. If a .venv directory is found in the working directory or any of the parent directories or the VIRTUAL_ENV environment variable is set, it will take precedence over any Python executables on the PATH.
To ignore virtual environments, use the --system flag:
$ uv python find --system\n
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#discovery-of-python-versions","level":2,"title":"Discovery of Python versions","text":"When searching for a Python version, the following locations are checked:
- Managed Python installations in the
UV_PYTHON_INSTALL_DIR. - A Python interpreter on the
PATH as python, python3, or python3.x on macOS and Linux, or python.exe on Windows. - On Windows, the Python interpreters in the Windows registry and Microsoft Store Python interpreters (see
py --list-paths) that match the requested version.
In some cases, uv allows using a Python version from a virtual environment. In this case, the virtual environment's interpreter will be checked for compatibility with the request before searching for an installation as described above. See the pip-compatible virtual environment discovery documentation for details.
When performing discovery, non-executable files will be ignored. Each discovered executable is queried for metadata to ensure it meets the requested Python version. If the query fails, the executable will be skipped. If the executable satisfies the request, it is used without inspecting additional executables.
When searching for a managed Python version, uv will prefer newer versions first. When searching for a system Python version, uv will use the first compatible version — not the newest version.
If a Python version cannot be found on the system, uv will check for a compatible managed Python version download.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#python-pre-releases","level":2,"title":"Python pre-releases","text":"Python pre-releases will not be selected by default. Python pre-releases will be used if there is no other available installation matching the request. For example, if only a pre-release version is available it will be used but otherwise a stable release version will be used. Similarly, if the path to a pre-release Python executable is provided then no other Python version matches the request and the pre-release version will be used.
If a pre-release Python version is available and matches the request, uv will not download a stable Python version instead.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#free-threaded-python","level":2,"title":"Free-threaded Python","text":"uv supports discovering and installing free-threaded Python variants in CPython 3.13+.
Free-threaded Python versions will not be selected by default. Free-threaded Python versions will only be selected when explicitly requested, e.g., with 3.13t or 3.13+freethreaded.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#debug-python-variants","level":2,"title":"Debug Python variants","text":"uv supports discovering and installing debug builds of Python, i.e., with debug assertions enabled.
Important
Debug builds of Python are slower and are not appropriate for general use.
Debug builds will be used if there is no other available installation matching the request. For example, if only a debug version is available it will be used but otherwise a stable release version will be used. Similarly, if the path to a debug Python executable is provided then no other Python version matches the request and the debug version will be used.
Debug builds of Python can be explicitly requested with, e.g., 3.13d or 3.13+debug.
Note
CPython versions installed by uv usually have debug symbols stripped to reduce the distribution size. These debug builds do not have debug symbols stripped, which can be useful when debugging Python processes with a C-level debugger.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#disabling-automatic-python-downloads","level":2,"title":"Disabling automatic Python downloads","text":"By default, uv will automatically download Python versions when needed.
The python-downloads option can be used to disable this behavior. By default, it is set to automatic; set to manual to only allow Python downloads during uv python install.
Tip
The python-downloads setting can be set in a persistent configuration file to change the default behavior, or the --no-python-downloads flag can be passed to any uv command.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#requiring-or-disabling-managed-python-versions","level":2,"title":"Requiring or disabling managed Python versions","text":"By default, uv will attempt to use Python versions found on the system and only download managed Python versions when necessary. To ignore system Python versions, and only use managed Python versions, use the --managed-python flag:
$ uv python list --managed-python\n
Similarly, to ignore managed Python versions and only use system Python versions, use the --no-managed-python flag:
$ uv python list --no-managed-python\n
To change uv's default behavior in a configuration file, use the python-preference setting.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#adjusting-python-version-preferences","level":2,"title":"Adjusting Python version preferences","text":"The python-preference setting determines whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv.
By default, the python-preference is set to managed which prefers managed Python installations over system Python installations. However, system Python installations are still preferred over downloading a managed Python version.
The following alternative options are available:
only-managed: Only use managed Python installations; never use system Python installations. Equivalent to --managed-python.system: Prefer system Python installations over managed Python installations.only-system: Only use system Python installations; never use managed Python installations. Equivalent to --no-managed-python.
Note
Automatic Python version downloads can be disabled without changing the preference.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#python-implementation-support","level":2,"title":"Python implementation support","text":"uv supports the CPython, PyPy, Pyodide, and GraalPy Python implementations. If a Python implementation is not supported, uv will fail to discover its interpreter.
The implementations may be requested with either the long or short name:
- CPython:
cpython, cp - PyPy:
pypy, pp - GraalPy:
graalpy, gp - Pyodide:
pyodide
Implementation name requests are not case-sensitive.
See the Python version request documentation for more details on the supported formats.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#managed-python-distributions","level":2,"title":"Managed Python distributions","text":"uv supports downloading and installing CPython, PyPy, and Pyodide distributions.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#cpython-distributions","level":3,"title":"CPython distributions","text":"As Python does not publish official distributable CPython binaries, uv instead uses pre-built distributions from the Astral python-build-standalone project. python-build-standalone is also is used in many other Python projects, like Mise and bazelbuild/rules_python.
The uv Python distributions are self-contained, highly-portable, and performant. While Python can be built from source, as in tools like pyenv, doing so requires preinstalled system dependencies, and creating optimized, performant builds (e.g., with PGO and LTO enabled) is very slow.
These distributions have some behavior quirks, generally as a consequence of portability; see the python-build-standalone quirks documentation for details.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#pypy-distributions","level":3,"title":"PyPy distributions","text":"PyPy distributions are provided by the PyPy project.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#pyodide-distributions","level":3,"title":"Pyodide distributions","text":"Pyodide distributions are provided by the Pyodide project.
Pyodide is a port of CPython for the WebAssembly / Emscripten platform.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#transparent-x86_64-emulation-on-aarch64","level":2,"title":"Transparent x86_64 emulation on aarch64","text":"Both macOS and Windows support running x86_64 binaries on aarch64 through transparent emulation. This is called Rosetta 2 or Windows on ARM (WoA) emulation. It's possible to use x86_64 uv on aarch64, and also possible to use an x86_64 Python interpreter on aarch64. Either uv binary can use either Python interpreter, but a Python interpreter needs packages for its architecture, either all x86_64 or all aarch64.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/python-versions/#registration-in-the-windows-registry","level":2,"title":"Registration in the Windows registry","text":"On Windows, installation of managed Python versions will register them with the Windows registry as defined by PEP 514.
After installation, the Python versions can be selected with the py launcher, e.g.:
$ uv python install 3.13.1\n$ py -V:Astral/CPython3.13.1\n
On uninstall, uv will remove the registry entry for the target version as well as any broken registry entries.
","path":["Concepts","Python versions"],"tags":[]},{"location":"concepts/resolution/","level":1,"title":"Resolution","text":"Resolution is the process of taking a list of requirements and converting them to a list of package versions that fulfill the requirements. Resolution requires recursively searching for compatible versions of packages, ensuring that the requested requirements are fulfilled and that the requirements of the requested packages are compatible.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#dependencies","level":2,"title":"Dependencies","text":"Most projects and packages have dependencies. Dependencies are other packages that are necessary in order for the current package to work. A package defines its dependencies as requirements, roughly a combination of a package name and acceptable versions. The dependencies defined by the current project are called direct dependencies. The dependencies added by each dependency of the current project are called indirect or transitive dependencies.
Note
See the dependency specifiers page in the Python Packaging documentation for details about dependencies.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#basic-examples","level":2,"title":"Basic examples","text":"To help demonstrate the resolution process, consider the following dependencies:
- The project depends on
foo and bar. foo has one version, 1.0.0: foo 1.0.0 depends on lib>=1.0.0.
bar has one version, 1.0.0: bar 1.0.0 depends on lib>=2.0.0.
lib has two versions, 1.0.0 and 2.0.0. Both versions have no dependencies.
In this example, the resolver must find a set of package versions which satisfies the project requirements. Since there is only one version of both foo and bar, those will be used. The resolution must also include the transitive dependencies, so a version of lib must be chosen. foo 1.0.0 allows all available versions of lib, but bar 1.0.0 requires lib>=2.0.0 so lib 2.0.0 must be used.
In some resolutions, there may be more than one valid solution. Consider the following dependencies:
- The project depends on
foo and bar. foo has two versions, 1.0.0 and 2.0.0: foo 1.0.0 has no dependencies.foo 2.0.0 depends on lib==2.0.0.
bar has two versions, 1.0.0 and 2.0.0: bar 1.0.0 has no dependencies.bar 2.0.0 depends on lib==1.0.0
lib has two versions, 1.0.0 and 2.0.0. Both versions have no dependencies.
In this example, some version of both foo and bar must be selected; however, determining which version requires considering the dependencies of each version of foo and bar. foo 2.0.0 and bar 2.0.0 cannot be installed together as they conflict on their required version of lib, so the resolver must select either foo 1.0.0 (along with bar 2.0.0) or bar 1.0.0 (along with foo 1.0.0). Both are valid solutions, and different resolution algorithms may yield either result.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#platform-markers","level":2,"title":"Platform markers","text":"Markers allow attaching an expression to requirements that indicate when the dependency should be used. For example bar ; python_version < \"3.9\" indicates that bar should only be installed on Python 3.8 and earlier.
Markers are used to adjust a package's dependencies based on the current environment or platform. For example, markers can be used to modify dependencies by operating system, CPU architecture, Python version, Python implementation, and more.
Note
See the environment markers section in the Python Packaging documentation for more details about markers.
Markers are important for resolution because their values change the required dependencies. Typically, Python package resolvers use the markers of the current platform to determine which dependencies to use since the package is often being installed on the current platform. However, for locking dependencies this is problematic — the lockfile would only work for developers using the same platform the lockfile was created on. To solve this problem, platform-independent, or \"universal\" resolvers exist.
uv supports both platform-specific and universal resolution.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#platform-specific-resolution","level":2,"title":"Platform-specific resolution","text":"By default, uv's pip interface, i.e., uv pip compile, produces a resolution that is platform-specific, like pip-tools. There is no way to use platform-specific resolution in the uv's project interface.
uv also supports resolving for specific, alternate platforms and Python versions with the --python-platform and --python-version options. For example, if using Python 3.12 on macOS, uv pip compile --python-platform linux --python-version 3.10 requirements.in can be used to produce a resolution for Python 3.10 on Linux instead. Unlike universal resolution, during platform-specific resolution, the provided --python-version is the exact python version to use, not a lower bound.
Note
Python's environment markers expose far more information about the current machine than can be expressed by a simple --python-platform argument. For example, the platform_version marker on macOS includes the time at which the kernel was built, which can (in theory) be encoded in package requirements. uv's resolver makes a best-effort attempt to generate a resolution that is compatible with any machine running on the target --python-platform, which should be sufficient for most use cases, but may lose fidelity for complex package and platform combinations.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#universal-resolution","level":2,"title":"Universal resolution","text":"uv's lockfile (uv.lock) is created with a universal resolution and is portable across platforms. This ensures that dependencies are locked for everyone working on the project, regardless of operating system, architecture, and Python version. The uv lockfile is created and modified by project commands such as uv lock, uv sync, and uv add.
Universal resolution is also available in uv's pip interface, i.e., uv pip compile, with the --universal flag. The resulting requirements file will contain markers to indicate which platform each dependency is relevant for.
During universal resolution, a package may be listed multiple times with different versions or URLs if different versions are needed for different platforms — the markers determine which version will be used. A universal resolution is often more constrained than a platform-specific resolution, since we need to take the requirements for all markers into account.
During universal resolution, all required packages must be compatible with the entire range of requires-python declared in the pyproject.toml. For example, if a project's requires-python is >=3.8, resolution will fail if all versions of given dependency require Python 3.9 or later, since the dependency lacks a usable version for (e.g.) Python 3.8, the lower bound of the project's supported range. In other words, the project's requires-python must be a subset of the requires-python of all its dependencies.
When selecting the compatible version for a given dependency, uv will (by default) attempt to choose the latest compatible version for each supported Python version. For example, if a project's requires-python is >=3.8, and the latest version of a dependency requires Python 3.9 or later, while all prior versions supporting Python 3.8, the resolver will select the latest version for users running Python 3.9 or later, and previous versions for users running Python 3.8.
When evaluating requires-python ranges for dependencies, uv only considers lower bounds and ignores upper bounds entirely. For example, >=3.8, <4 is treated as >=3.8. Respecting upper bounds on requires-python often leads to formally correct but practically incorrect resolutions, as, e.g., resolvers will backtrack to the first published version that omits the upper bound (see: Requires-Python upper limits).
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#limited-resolution-environments","level":2,"title":"Limited resolution environments","text":"By default, the universal resolver attempts to solve for all platforms and Python versions.
If your project supports only a limited set of platforms or Python versions, you can constrain the set of solved platforms via the environments setting, which accepts a list of PEP 508 environment markers. In other words, you can use the environments setting to reduce the set of supported platforms.
For example, to constrain the lockfile to macOS and Linux, and avoid solving for Windows:
pyproject.toml[tool.uv]\nenvironments = [\n \"sys_platform == 'darwin'\",\n \"sys_platform == 'linux'\",\n]\n
Or, to avoid solving for alternative Python implementations:
pyproject.toml[tool.uv]\nenvironments = [\n \"implementation_name == 'cpython'\"\n]\n
Entries in the environments setting must be disjoint (i.e., they must not overlap). For example, sys_platform == 'darwin' and sys_platform == 'linux' are disjoint, but sys_platform == 'darwin' and python_version >= '3.9' are not, since both could be true at the same time.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#required-environments","level":2,"title":"Required environments","text":"In the Python ecosystem, packages can be published as source distributions, built distributions (wheels), or both; but to install a package, a built distribution is required. If a package lacks a built distribution, or lacks a distribution for the current platform or Python version (built distributions are often platform-specific), uv will attempt to build the package from source, then install the resulting built distribution.
Some packages (like PyTorch) publish built distributions, but omit a source distribution. Such packages are only installable on platforms for which a built distribution is available. For example, if a package publishes built distributions for Linux, but not macOS or Windows, then that package will only be installable on Linux.
Packages that lack source distributions cause problems for universal resolution, since there will typically be at least one platform or Python version for which the package is not installable.
By default, uv requires each such package to include at least one wheel that is compatible with the target Python version. The required-environments setting can be used to ensure that the resulting resolution contains wheels for specific platforms, or fails if no such wheels are available. The setting accepts a list of PEP 508 environment markers.
While the environments setting limits the set of environments that uv will consider when resolving dependencies, required-environments expands the set of platforms that uv must support when resolving dependencies.
For example, environments = [\"sys_platform == 'darwin'\"] would limit uv to solving for macOS (and ignoring Linux and Windows). On the other hand, required-environments = [\"sys_platform == 'darwin'\"] would require that any package without a source distribution include a wheel for macOS in order to be installable (and would fail if no such wheel is available).
In practice, required-environments can be useful for declaring explicit support for non-latest platforms, since this often requires backtracking past the latest published versions of those packages. For example, to guarantee that any built distribution-only packages includes support for Intel macOS:
pyproject.toml[tool.uv]\nrequired-environments = [\n \"sys_platform == 'darwin' and platform_machine == 'x86_64'\"\n]\n
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#dependency-preferences","level":2,"title":"Dependency preferences","text":"If resolution output file exists, i.e., a uv lockfile (uv.lock) or a requirements output file (requirements.txt), uv will prefer the dependency versions listed there. Similarly, if installing a package into a virtual environment, uv will prefer the already installed version if present. This means that locked or installed versions will not change unless an incompatible version is requested or an upgrade is explicitly requested with --upgrade.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#resolution-strategy","level":2,"title":"Resolution strategy","text":"By default, uv tries to use the latest version of each package. For example, uv pip install flask>=2.0.0 will install the latest version of Flask, e.g., 3.0.0. If flask>=2.0.0 is a dependency of the project, only flask 3.0.0 will be used. This is important, for example, because running tests will not check that the project is actually compatible with its stated lower bound of flask 2.0.0.
With --resolution lowest, uv will install the lowest possible version for all dependencies, both direct and indirect (transitive). Alternatively, --resolution lowest-direct will use the lowest compatible versions for all direct dependencies, while using the latest compatible versions for all other dependencies. uv will always use the latest versions for build dependencies.
For example, given the following requirements.in file:
requirements.inflask>=2.0.0\n
Running uv pip compile requirements.in would produce the following requirements.txt file:
requirements.txt# This file was autogenerated by uv via the following command:\n# uv pip compile requirements.in\nblinker==1.7.0\n # via flask\nclick==8.1.7\n # via flask\nflask==3.0.0\nitsdangerous==2.1.2\n # via flask\njinja2==3.1.2\n # via flask\nmarkupsafe==2.1.3\n # via\n # jinja2\n # werkzeug\nwerkzeug==3.0.1\n # via flask\n
However, uv pip compile --resolution lowest requirements.in would instead produce:
requirements.in# This file was autogenerated by uv via the following command:\n# uv pip compile requirements.in --resolution lowest\nclick==7.1.2\n # via flask\nflask==2.0.0\nitsdangerous==2.0.0\n # via flask\njinja2==3.0.0\n # via flask\nmarkupsafe==2.0.0\n # via jinja2\nwerkzeug==2.0.0\n # via flask\n
When publishing libraries, it is recommended to separately run tests with --resolution lowest or --resolution lowest-direct in continuous integration to ensure compatibility with the declared lower bounds.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#pre-release-handling","level":2,"title":"Pre-release handling","text":"By default, uv will accept pre-release versions during dependency resolution in two cases:
- If the package is a direct dependency, and its version specifiers include a pre-release specifier (e.g.,
flask>=2.0.0rc1). - If all published versions of a package are pre-releases.
If dependency resolution fails due to a transitive pre-release, uv will prompt use of --prerelease allow to allow pre-releases for all dependencies.
Alternatively, the transitive dependency can be added as a constraint or direct dependency (i.e. in requirements.in or pyproject.toml) with a pre-release version specifier (e.g., flask>=2.0.0rc1) to opt in to pre-release support for that specific dependency.
Pre-releases are notoriously difficult to model, and are a frequent source of bugs in other packaging tools. uv's pre-release handling is intentionally limited and requires user opt-in for pre-releases to ensure correctness.
For more details, see Pre-release compatibility.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#multi-version-resolution","level":2,"title":"Multi-version resolution","text":"During universal resolution, a package may be listed multiple times with different versions or URLs within the same lockfile, since different versions may be needed for different platforms or Python versions.
The --fork-strategy setting can be used to control how uv trades off between (1) minimizing the number of selected versions and (2) selecting the latest-possible version for each platform. The former leads to greater consistency across platforms, while the latter leads to use of newer package versions where possible.
By default (--fork-strategy requires-python), uv will optimize for selecting the latest version of each package for each supported Python version, while minimizing the number of selected versions across platforms.
For example, when resolving numpy with a Python requirement of >=3.8, uv would select the following versions:
numpy==1.24.4 ; python_version == \"3.8\"\nnumpy==2.0.2 ; python_version == \"3.9\"\nnumpy==2.2.0 ; python_version >= \"3.10\"\n
This resolution reflects the fact that NumPy 2.2.0 and later require at least Python 3.10, while earlier versions are compatible with Python 3.8 and 3.9.
Under --fork-strategy fewest, uv will instead 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.
For example, when in the scenario above, uv would select numpy==1.24.4 for all Python versions, rather than upgrading to numpy==2.0.2 for Python 3.9 and numpy==2.2.0 for Python 3.10 and later.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#dependency-constraints","level":2,"title":"Dependency constraints","text":"Like pip, uv supports constraint files (--constraint constraints.txt) which narrow the set of acceptable versions for the given packages. Constraint files are similar to requirements files, but being listed as a constraint alone will not cause a package to be included to the resolution. Instead, constraints only take effect if a requested package is already pulled in as a direct or transitive dependency. Constraints are useful for reducing the range of available versions for a transitive dependency. They can also be used to keep a resolution in sync with some other set of resolved versions, regardless of which packages are overlapping between the two.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#dependency-overrides","level":2,"title":"Dependency overrides","text":"Dependency overrides allow bypassing unsuccessful or undesirable resolutions by overriding a package's declared dependencies. Overrides are a useful last resort for cases in which you know that a dependency is compatible with a certain version of a package, despite the metadata indicating otherwise.
For example, if a transitive dependency declares the requirement pydantic>=1.0,<2.0, but does work with pydantic>=2.0, the user can override the declared dependency by including pydantic>=1.0,<3 in the overrides, thereby allowing the resolver to choose a newer version of pydantic.
Concretely, if pydantic>=1.0,<3 is included as an override, uv will ignore all declared requirements on pydantic, replacing them with the override. In the above example, the pydantic>=1.0,<2.0 requirement would be ignored completely, and would instead be replaced with pydantic>=1.0,<3.
While constraints can only reduce the set of acceptable versions for a package, overrides can expand the set of acceptable versions, providing an escape hatch for erroneous upper version bounds. As with constraints, overrides do not add a dependency on the package and only take effect if the package is requested in a direct or transitive dependency.
In a pyproject.toml, use tool.uv.override-dependencies to define a list of overrides. In the pip-compatible interface, the --override option can be used to pass files with the same format as constraints files.
If multiple overrides are provided for the same package, they must be differentiated with markers. If a package has a dependency with a marker, it is replaced unconditionally when using overrides — it does not matter if the marker evaluates to true or false.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#dependency-metadata","level":2,"title":"Dependency metadata","text":"During resolution, uv needs to resolve the metadata for each package it encounters, in order to determine its dependencies. This metadata is often available as a static file in the package index; however, for packages that only provide source distributions, the metadata may not be available upfront.
In such cases, uv has to build the package to determine its metadata (e.g., by invoking setup.py). This can introduce a performance penalty during resolution. Further, it imposes the requirement that the package can be built on all platforms, which may not be true.
For example, you may have a package that should only be built and installed on Linux, but doesn't build successfully on macOS or Windows. While uv can construct a perfectly valid lockfile for this scenario, doing so would require building the package, which would fail on non-Linux platforms.
The tool.uv.dependency-metadata table can be used to provide static metadata for such dependencies upfront, thereby allowing uv to skip the build step and use the provided metadata instead.
For example, to provide metadata for chumpy upfront, include its dependency-metadata in the pyproject.toml:
[[tool.uv.dependency-metadata]]\nname = \"chumpy\"\nversion = \"0.70\"\nrequires-dist = [\"numpy>=1.8.1\", \"scipy>=0.13.0\", \"six>=1.11.0\"]\n
These declarations are intended for cases in which a package does not declare static metadata upfront, though they are also useful for packages that require disabling build isolation In such cases, it may be easier to declare the package metadata upfront, rather than creating a custom build environment prior to resolving the package.
For example, past versions of flash-attn did not declare static metadata. By declaring metadata for flash-attn upfront, uv can resolve flash-attn without building the package from source (which itself requires installing torch):
[project]\nname = \"project\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12\"\ndependencies = [\"flash-attn\"]\n\n[tool.uv.sources]\nflash-attn = { git = \"https://github.com/Dao-AILab/flash-attention\", tag = \"v2.6.3\" }\n\n[[tool.uv.dependency-metadata]]\nname = \"flash-attn\"\nversion = \"2.6.3\"\nrequires-dist = [\"torch\", \"einops\"]\n
Like dependency overrides, tool.uv.dependency-metadata can also be used for cases in which a package's metadata is incorrect or incomplete, or when a package is not available in the package index. While dependency overrides allow overriding the allowed versions of a package globally, metadata overrides allow overriding the declared metadata of a specific package.
Note
The version field in tool.uv.dependency-metadata is optional for registry-based dependencies (when omitted, uv will assume the metadata applies to all versions of the package), but required for direct URL dependencies (like Git dependencies).
Entries in the tool.uv.dependency-metadata table follow the Metadata 2.3 specification, though only name, version, requires-dist, requires-python, and provides-extra are read by uv. The version field is also considered optional. If omitted, the metadata will be used for all versions of the specified package.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#conflicting-dependencies","level":2,"title":"Conflicting dependencies","text":"uv requires that all dependencies declared by a project are compatible with each other and resolves all dependencies together when creating the lockfile. This includes project dependencies, optional dependencies (\"extras\"), and dependency groups (development dependencies).
If dependencies declared in one extra are not compatible with those in another extra, uv will fail to resolve the requirements of the project with an error. For example, consider two sets of optional dependencies that conflict with one another:
pyproject.toml[project.optional-dependencies]\nextra1 = [\"numpy==2.1.2\"]\nextra2 = [\"numpy==2.0.0\"]\n
If you run uv lock with the above dependencies, resolution will fail:
$ uv lock\n x No solution found when resolving dependencies:\n `-> Because myproject[extra2] depends on numpy==2.0.0 and myproject[extra1] depends on numpy==2.1.2, we can conclude that myproject[extra1] and\n myproject[extra2] are incompatible.\n And because your project requires myproject[extra1] and myproject[extra2], we can conclude that your projects's requirements are unsatisfiable.\n
To work around this, uv supports explicit declaration of conflicts. If you specify that extra1 and extra2 are conflicting, uv will resolve them separately. Specify conflicts in the tool.uv section:
pyproject.toml[tool.uv]\nconflicts = [\n [\n { extra = \"extra1\" },\n { extra = \"extra2\" },\n ],\n]\n
Now, running uv lock will succeed. However, now you cannot install both extra1 and extra2 at the same time:
$ uv sync --extra extra1 --extra extra2\nResolved 3 packages in 14ms\nerror: extra `extra1`, extra `extra2` are incompatible with the declared conflicts: {`myproject[extra1]`, `myproject[extra2]`}\n
This error occurs because installing both extra1 and extra2 would result in installing two different versions of a package into the same environment.
The above strategy for dealing with conflicting optional dependencies also works with dependency groups:
pyproject.toml[dependency-groups]\ngroup1 = [\"numpy==2.1.2\"]\ngroup2 = [\"numpy==2.0.0\"]\n\n[tool.uv]\nconflicts = [\n [\n { group = \"group1\" },\n { group = \"group2\" },\n ],\n]\n
The only difference from conflicting extras is that you need to use the group key instead of extra.
When using a workspace with multiple projects, the same restrictions apply — uv requires all workspace members to be compatible with each other. Similarly, conflicts can be declared across workspace members.
For example, consider the following workspace:
member1/pyproject.toml[project]\nname = \"member1\"\n\n[project.optional-dependencies]\nextra1 = [\"numpy==2.1.2\"]\n
member2/pyproject.toml[project]\nname = \"member2\"\n\n[project.optional-dependencies]\nextra2 = [\"numpy==2.0.0\"]\n
To declare a conflict between extras in these different workspace members, use the package key:
pyproject.toml[tool.uv]\nconflicts = [\n [\n { package = \"member1\", extra = \"extra1\" },\n { package = \"member2\", extra = \"extra2\" },\n ],\n]\n
It's also possible for the project dependencies (i.e., project.dependencies) of one workspace member to conflict with the extra of another member, for example:
member1/pyproject.toml[project]\nname = \"member1\"\ndependencies = [\"numpy==2.1.2\"]\n
member2/pyproject.toml[project]\nname = \"member2\"\n\n[project.optional-dependencies]\nextra2 = [\"numpy==2.0.0\"]\n
This conflict can also be declared using the package key:
pyproject.toml[tool.uv]\nconflicts = [\n [\n { package = \"member1\" },\n { package = \"member2\", extra = \"extra2\" },\n ],\n]\n
Similarly, it's possible for some workspace members to have conflicting project dependencies:
member1/pyproject.toml[project]\nname = \"member1\"\ndependencies = [\"numpy==2.1.2\"]\n
member2/pyproject.toml[project]\nname = \"member2\"\ndependencies = [\"numpy==2.0.0\"]\n
This conflict can also be declared using the package key:
pyproject.toml[tool.uv]\nconflicts = [\n [\n { package = \"member1\" },\n { package = \"member2\" },\n ],\n]\n
These workspace members will not be installable together, e.g., the workspace root cannot define:
pyproject.toml[project]\nname = \"root\"\ndependencies = [\"member1\", \"member2\"]\n
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#lower-bounds","level":2,"title":"Lower bounds","text":"By default, uv add adds lower bounds to dependencies and, when using uv to manage projects, uv will warn if direct dependencies don't have lower bound.
Lower bounds are not critical in the \"happy path\", but they are important for cases where there are dependency conflicts. For example, consider a project that requires two packages and those packages have conflicting dependencies. The resolver needs to check all combinations of all versions within the constraints for the two packages — if all of them conflict, an error is reported because the dependencies are not satisfiable. If there are no lower bounds, the resolver can (and often will) backtrack down to the oldest version of a package. This isn't only problematic because it's slow, the old version of the package often fails to build, or the resolver can end up picking a version that's old enough that it doesn't depend on the conflicting package, but also doesn't work with your code.
Lower bounds are particularly critical when writing a library. It's important to declare the lowest version for each dependency that your library works with, and to validate that the bounds are correct — testing with --resolution lowest or --resolution lowest-direct. Otherwise, a user may receive an old, incompatible version of one of your library's dependencies and the library will fail with an unexpected error.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#reproducible-resolutions","level":2,"title":"Reproducible resolutions","text":"uv supports an --exclude-newer option to limit resolution to distributions published before a specific date, allowing reproduction of installations regardless of new package releases. The date may be specified as an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or a local date in the same format (e.g., 2006-12-02) in your system's configured time zone.
Note the package index must support the upload-time field as specified in PEP 700. If the field is not present for a given distribution, the distribution will be treated as unavailable. PyPI provides upload-time for all packages.
To ensure reproducibility, messages for unsatisfiable resolutions will not mention that distributions were excluded due to the --exclude-newer flag — newer distributions will be treated as if they do not exist.
Note
The --exclude-newer option is only applied to packages that are read from a registry (as opposed to, e.g., Git dependencies). Further, when using the uv pip interface, uv will not downgrade previously installed packages unless the --reinstall flag is provided, in which case uv will perform a new resolution.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#source-distribution","level":2,"title":"Source distribution","text":"PEP 625 specifies that packages must distribute source distributions as gzip tarball (.tar.gz) archives. Prior to this specification, other archive formats, which need to be supported for backward compatibility, were also allowed. uv supports reading and extracting archives in the following formats:
- gzip tarball (
.tar.gz, .tgz) - bzip2 tarball (
.tar.bz2, .tbz) - xz tarball (
.tar.xz, .txz) - zstd tarball (
.tar.zst) - lzip tarball (
.tar.lz) - lzma tarball (
.tar.lzma) - zip (
.zip)
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#lockfile-versioning","level":2,"title":"Lockfile versioning","text":"The uv.lock file uses a versioned schema. The schema version is included in the version field of the lockfile.
Any given version of uv can read and write lockfiles with the same schema version, but will reject lockfiles with a greater schema version. For example, if your uv version supports schema v1, uv lock will error if it encounters an existing lockfile with schema v2.
uv versions that support schema v2 may be able to read lockfiles with schema v1 if the schema update was backwards-compatible. However, this is not guaranteed, and uv may exit with an error if it encounters a lockfile with an outdated schema version.
The schema version is considered part of the public API, and so is only bumped in minor releases, as a breaking change (see Versioning). As such, all uv patch versions within a given minor uv release are guaranteed to have full lockfile compatibility. In other words, lockfiles may only be rejected across minor releases.
The revision field of the lockfile is used to track backwards compatible changes to the lockfile. For example, adding a new field to distributions. Changes to the revision will not cause older versions of uv to error.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/resolution/#learn-more","level":2,"title":"Learn more","text":"For more details about the internals of the resolver, see the resolver reference documentation.
","path":["Concepts","Resolution"],"tags":[]},{"location":"concepts/tools/","level":1,"title":"Tools","text":"Tools are Python packages that provide command-line interfaces.
Note
See the tools guide for an introduction to working with the tools interface — this document discusses details of tool management.
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/tools/#the-uv-tool-interface","level":2,"title":"The uv tool interface","text":"uv includes a dedicated interface for interacting with tools. Tools can be invoked without installation using uv tool run, in which case their dependencies are installed in a temporary virtual environment isolated from the current project.
Because it is very common to run tools without installing them, a uvx alias is provided for uv tool run — the two commands are exactly equivalent. For brevity, the documentation will mostly refer to uvx instead of uv tool run.
Tools can also be installed with uv tool install, in which case their executables are available on the PATH — an isolated virtual environment is still used, but it is not removed when the command completes.
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/tools/#execution-vs-installation","level":2,"title":"Execution vs installation","text":"In most cases, executing a tool with uvx is more appropriate than installing the tool. Installing the tool is useful if you need the tool to be available to other programs on your system, e.g., if some script you do not control requires the tool, or if you are in a Docker image and want to make the tool available to users.
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/tools/#tool-environments","level":2,"title":"Tool environments","text":"When running a tool with uvx, a virtual environment is stored in the uv cache directory and is treated as disposable, i.e., if you run uv cache clean the environment will be deleted. The environment is only cached to reduce the overhead of repeated invocations. If the environment is removed, a new one will be created automatically.
When installing a tool with uv tool install, a virtual environment is created in the uv tools directory. The environment will not be removed unless the tool is uninstalled. If the environment is manually deleted, the tool will fail to run.
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/tools/#tool-versions","level":2,"title":"Tool versions","text":"Unless a specific version is requested, uv tool install will install the latest available of the requested tool. uvx will use the latest available version of the requested tool on the first invocation. After that, uvx will use the cached version of the tool unless a different version is requested, the cache is pruned, or the cache is refreshed.
For example, to run a specific version of Ruff:
$ uvx ruff@0.6.0 --version\nruff 0.6.0\n
A subsequent invocation of uvx will use the latest, not the cached, version.
$ uvx ruff --version\nruff 0.6.2\n
But, if a new version of Ruff was released, it would not be used unless the cache was refreshed.
To request the latest version of Ruff and refresh the cache, use the @latest suffix:
$ uvx ruff@latest --version\n0.6.2\n
Once a tool is installed with uv tool install, uvx will use the installed version by default.
For example, after installing an older version of Ruff:
$ uv tool install ruff==0.5.0\n
The version of ruff and uvx ruff is the same:
$ ruff --version\nruff 0.5.0\n$ uvx ruff --version\nruff 0.5.0\n
However, you can ignore the installed version by requesting the latest version explicitly, e.g.:
$ uvx ruff@latest --version\n0.6.2\n
Or, by using the --isolated flag, which will avoid refreshing the cache but ignore the installed version:
$ uvx --isolated ruff --version\n0.6.2\n
uv tool install will also respect the {package}@{version} and {package}@latest specifiers, as in:
$ uv tool install ruff@latest\n$ uv tool install ruff@0.6.0\n
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/tools/#tools-directory","level":2,"title":"Tools directory","text":"By default, the uv tools directory is named tools and is in the uv application state directory, e.g., ~/.local/share/uv/tools. The location may be customized with the UV_TOOL_DIR environment variable.
To display the path to the tool installation directory:
$ uv tool dir\n
Tool environments are placed in a directory with the same name as the tool package, e.g., .../tools/<name>.
Important
Tool environments are not intended to be mutated directly. It is strongly recommended never to mutate a tool environment manually, e.g., with a pip operation.
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/tools/#upgrading-tools","level":2,"title":"Upgrading tools","text":"Tool environments may be upgraded via uv tool upgrade, or re-created entirely via subsequent uv tool install operations.
To upgrade all packages in a tool environment
$ uv tool upgrade black\n
To upgrade a single package in a tool environment:
$ uv tool upgrade black --upgrade-package click\n
Tool upgrades will respect the version constraints provided when installing the tool. For example, uv tool install black >=23,<24 followed by uv tool upgrade black will upgrade Black to the latest version in the range >=23,<24.
To instead replace the version constraints, reinstall the tool with uv tool install:
$ uv tool install black>=24\n
Similarly, tool upgrades will retain the settings provided when installing the tool. For example, uv tool install black --prerelease allow followed by uv tool upgrade black will retain the --prerelease allow setting.
Note
Tool upgrades will reinstall the tool executables, even if they have not changed.
To reinstall packages during upgrade, use the --reinstall and --reinstall-package options.
To reinstall all packages in a tool environment
$ uv tool upgrade black --reinstall\n
To reinstall a single package in a tool environment:
$ uv tool upgrade black --reinstall-package click\n
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/tools/#including-additional-dependencies","level":2,"title":"Including additional dependencies","text":"Additional packages can be included during tool execution:
$ uvx --with <extra-package> <tool>\n
And, during tool installation:
$ uv tool install --with <extra-package> <tool-package>\n
The --with option can be provided multiple times to include additional packages.
The --with option supports package specifications, so a specific version can be requested:
$ uvx --with <extra-package>==<version> <tool-package>\n
The -w shorthand can be used in place of the --with option:
$ uvx -w <extra-package> <tool-package>\n
If the requested version conflicts with the requirements of the tool package, package resolution will fail and the command will error.
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/tools/#installing-executables-from-additional-packages","level":2,"title":"Installing executables from additional packages","text":"When installing a tool, you may want to include executables from additional packages in the same tool environment. This is useful when you have related tools that work together or when you want to install multiple executables that share dependencies.
The --with-executables-from option allows you to specify additional packages whose executables should be installed alongside the main tool:
$ uv tool install --with-executables-from <package1>,<package2> <tool-package>\n
For example, to install Ansible along with executables from ansible-core and ansible-lint:
$ uv tool install --with-executables-from ansible-core,ansible-lint ansible\n
This will install all executables from the ansible, ansible-core, and ansible-lint packages into the same tool environment, making them all available on the PATH.
The --with-executables-from option can be combined with other installation options:
$ uv tool install --with-executables-from ansible-core --with mkdocs-material ansible\n
Note that --with-executables-from differs from --with in that:
--with includes additional packages as dependencies but does not install their executables--with-executables-from includes both the packages as dependencies and installs their executables
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/tools/#python-versions","level":2,"title":"Python versions","text":"Each tool environment is linked to a specific Python version. This uses the same Python version discovery logic as other virtual environments created by uv, but will ignore non-global Python version requests like .python-version files and the requires-python value from a pyproject.toml.
The --python option can be used to request a specific version. See the Python version documentation for more details.
If the Python version used by a tool is uninstalled, the tool environment will be broken and the tool may be unusable.
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/tools/#tool-executables","level":2,"title":"Tool executables","text":"Tool executables include all console entry points, script entry points, and binary scripts provided by a Python package. Tool executables are symlinked into the bin directory on Unix and copied on Windows.
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/tools/#the-bin-directory","level":3,"title":"The bin directory","text":"Executables are installed into the user bin directory following the XDG standard, e.g., ~/.local/bin. Unlike other directory schemes in uv, the XDG standard is used on all platforms notably including Windows and macOS — there is no clear alternative location to place executables on these platforms. The installation directory is determined from the first available environment variable:
$UV_TOOL_BIN_DIR$XDG_BIN_HOME$XDG_DATA_HOME/../bin$HOME/.local/bin
Executables provided by dependencies of tool packages are not installed.
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/tools/#the-path","level":3,"title":"The PATH","text":"The bin directory must be in the PATH variable for tool executables to be available from the shell. If it is not in the PATH, a warning will be displayed. The uv tool update-shell command can be used to add the bin directory to the PATH in common shell configuration files.
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/tools/#overwriting-executables","level":3,"title":"Overwriting executables","text":"Installation of tools will not overwrite executables in the bin directory that were not previously installed by uv. For example, if pipx has been used to install a tool, uv tool install will fail. The --force flag can be used to override this behavior.
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/tools/#relationship-to-uv-run","level":2,"title":"Relationship to uv run","text":"The invocation uv tool run <name> (or uvx <name>) is nearly equivalent to:
$ uv run --no-project --with <name> -- <name>\n
However, there are a couple notable differences when using uv's tool interface:
- The
--with option is not needed — the required package is inferred from the command name. - The temporary environment is cached in a dedicated location.
- The
--no-project flag is not needed — tools are always run isolated from the project. - If a tool is already installed,
uv tool run will use the installed version but uv run will not.
If the tool should not be isolated from the project, e.g., when running pytest or mypy, then uv run should be used instead of uv tool run.
","path":["Concepts","Tools"],"tags":[]},{"location":"concepts/authentication/","level":1,"title":"Authentication","text":"Authentication is required when working with private repositories or package indexes.
Learn more about authentication in uv:
- Using the
uv auth CLI - HTTP authentication
- Git authentication
- TLS certificates
- Third-party services
","path":["Concepts","Authentication"],"tags":[]},{"location":"concepts/authentication/certificates/","level":1,"title":"TLS certificates","text":"By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS, where reading the system trust store incurs a significant delay).
","path":["Concepts","Authentication","TLS certificates"],"tags":[]},{"location":"concepts/authentication/certificates/#system-certificates","level":2,"title":"System certificates","text":"In some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store. To instruct uv to use the system's trust store, run uv with the --native-tls command-line flag, or set the UV_NATIVE_TLS environment variable to true.
","path":["Concepts","Authentication","TLS certificates"],"tags":[]},{"location":"concepts/authentication/certificates/#custom-certificates","level":2,"title":"Custom certificates","text":"If a direct path to the certificate is required (e.g., in CI), set the SSL_CERT_FILE environment variable to the path of the certificate bundle, to instruct uv to use that file instead of the system's trust store.
If client certificate authentication (mTLS) is desired, set the SSL_CLIENT_CERT environment variable to the path of the PEM formatted file containing the certificate followed by the private key.
","path":["Concepts","Authentication","TLS certificates"],"tags":[]},{"location":"concepts/authentication/certificates/#insecure-hosts","level":2,"title":"Insecure hosts","text":"If you're using a setup in which you want to trust a self-signed certificate or otherwise disable certificate verification, you can instruct uv to allow insecure connections to dedicated hosts via the allow-insecure-host configuration option. For example, adding the following to pyproject.toml will allow insecure connections to example.com:
[tool.uv]\nallow-insecure-host = [\"example.com\"]\n
allow-insecure-host expects to receive a hostname (e.g., localhost) or hostname-port pair (e.g., localhost:8080), and is only applicable to HTTPS connections, as HTTP connections are inherently insecure.
Use allow-insecure-host with caution and only in trusted environments, as it can expose you to security risks due to the lack of certificate verification.
","path":["Concepts","Authentication","TLS certificates"],"tags":[]},{"location":"concepts/authentication/cli/","level":1,"title":"The uv auth CLI","text":"uv provides a high-level interface for storing and retrieving credentials from services.
","path":["Concepts","Authentication","The uv auth CLI"],"tags":[]},{"location":"concepts/authentication/cli/#logging-in-to-a-service","level":2,"title":"Logging in to a service","text":"To add credentials for service, use the uv auth login command:
$ uv auth login example.com\n
This will prompt for the credentials.
The credentials can also be provided using the --username and --password options, or the --token option for services which use a __token__ or arbitrary username.
Note
We recommend providing the secret via stdin. Use - to indicate the value should be read from stdin, e.g., for --password:
$ echo 'my-password' | uv auth login example.com --password -\n
The same pattern can be used with --token.
Once credentials are added, uv will use them for packaging operations that require fetching content from the given service. At this time, only HTTPS Basic authentication is supported. The credentials will not yet be used for Git requests.
Note
The credentials will not be validated, i.e., incorrect credentials will not fail.
","path":["Concepts","Authentication","The uv auth CLI"],"tags":[]},{"location":"concepts/authentication/cli/#logging-out-of-a-service","level":2,"title":"Logging out of a service","text":"To remove credentials, use the uv auth logout command:
$ uv auth logout example.com\n
Note
The credentials will not be invalidated with the remote server, i.e., they will only be removed from local storage not rendered unusable.
","path":["Concepts","Authentication","The uv auth CLI"],"tags":[]},{"location":"concepts/authentication/cli/#showing-credentials-for-a-service","level":2,"title":"Showing credentials for a service","text":"To show the credential stored for a given URL, use the uv auth token command:
$ uv auth token example.com\n
If a username was used to log in, it will need to be provided as well, e.g.:
$ uv auth token --username foo example.com\n
","path":["Concepts","Authentication","The uv auth CLI"],"tags":[]},{"location":"concepts/authentication/cli/#configuring-the-storage-backend","level":2,"title":"Configuring the storage backend","text":"Credentials are persisted to the uv credentials store.
By default, credentials are written to a plaintext file. An encrypted system-native storage backend can be enabled with UV_PREVIEW_FEATURES=native-auth.
","path":["Concepts","Authentication","The uv auth CLI"],"tags":[]},{"location":"concepts/authentication/git/","level":1,"title":"Git credentials","text":"uv allows packages to be installed from private Git repositories using SSH or HTTP authentication.
","path":["Concepts","Authentication","Git credentials"],"tags":[]},{"location":"concepts/authentication/git/#ssh-authentication","level":2,"title":"SSH authentication","text":"To authenticate using an SSH key, use the ssh:// protocol:
git+ssh://git@<hostname>/... (e.g., git+ssh://git@github.com/astral-sh/uv)git+ssh://git@<host>/... (e.g., git+ssh://git@github.com-key-2/astral-sh/uv)
SSH authentication requires using the username git.
See the GitHub SSH documentation for more details on how to configure SSH.
","path":["Concepts","Authentication","Git credentials"],"tags":[]},{"location":"concepts/authentication/git/#http-authentication","level":3,"title":"HTTP authentication","text":"To authenticate over HTTP Basic authentication using a password or token:
git+https://<user>:<token>@<hostname>/... (e.g., git+https://git:github_pat_asdf@github.com/astral-sh/uv)git+https://<token>@<hostname>/... (e.g., git+https://github_pat_asdf@github.com/astral-sh/uv)git+https://<user>@<hostname>/... (e.g., git+https://git@github.com/astral-sh/uv)
Note
When using a GitHub personal access token, the username is arbitrary. GitHub doesn't allow you to use your account name and password in URLs like this, although other hosts may.
If there are no credentials present in the URL and authentication is needed, the Git credential helper will be queried.
","path":["Concepts","Authentication","Git credentials"],"tags":[]},{"location":"concepts/authentication/git/#persistence-of-credentials","level":2,"title":"Persistence of credentials","text":"When using uv add, uv will not persist Git credentials to the pyproject.toml or uv.lock. These files are often included in source control and distributions, so it is generally unsafe to include credentials in them.
If you have a Git credential helper configured, your credentials may be automatically persisted, resulting in successful subsequent fetches of the dependency. However, if you do not have a Git credential helper or the project is used on a machine without credentials seeded, uv will fail to fetch the dependency.
You may force uv to persist Git credentials by passing the --raw option to uv add. However, we strongly recommend setting up a credential helper instead.
","path":["Concepts","Authentication","Git credentials"],"tags":[]},{"location":"concepts/authentication/git/#git-credential-helpers","level":2,"title":"Git credential helpers","text":"Git credential helpers are used to store and retrieve Git credentials. See the Git documentation to learn more.
If you're using GitHub, the simplest way to set up a credential helper is to install the gh CLI and use:
$ gh auth login\n
See the gh auth login documentation for more details.
Note
When using gh auth login interactively, the credential helper will be configured automatically. But when using gh auth login --with-token, as in the uv GitHub Actions guide, the gh auth setup-git command will need to be run afterwards to configure the credential helper.
","path":["Concepts","Authentication","Git credentials"],"tags":[]},{"location":"concepts/authentication/http/","level":1,"title":"HTTP credentials","text":"uv supports credentials over HTTP when querying package registries.
Authentication can come from the following sources, in order of precedence:
- The URL, e.g.,
https://<user>:<password>@<hostname>/... - A netrc configuration file
- The uv credentials store
- A keyring provider (off by default)
Authentication may be used for hosts specified in the following contexts:
[index]index-urlextra-index-urlfind-linkspackage @ https://...
","path":["Concepts","Authentication","HTTP credentials"],"tags":[]},{"location":"concepts/authentication/http/#netrc-files","level":2,"title":"netrc files","text":".netrc files are a long-standing plain text format for storing credentials on a system.
Reading credentials from .netrc files is always enabled. The target file path will be loaded from the NETRC environment variable if defined, falling back to ~/.netrc if not.
","path":["Concepts","Authentication","HTTP credentials"],"tags":[]},{"location":"concepts/authentication/http/#the-uv-credentials-store","level":2,"title":"The uv credentials store","text":"uv can read and write credentials from a store using the uv auth commands.
Credentials are stored in a plaintext file in uv's state directory, e.g., ~/.local/share/uv/credentials/credentials.toml on Unix. This file is currently not intended to be edited manually.
Note
A secure, system native storage mechanism is in preview — it is still experimental and being actively developed. In the future, this will become the default storage mechanism.
When enabled, uv will use the secret storage mechanism native to your operating system. On macOS, it uses the Keychain Services. On Windows, it uses the Windows Credential Manager. On Linux, it uses the DBus-based Secret Service API.
Currently, uv only searches the native store for credentials it has added to the secret store — it will not retrieve credentials persisted by other applications.
Set UV_PREVIEW_FEATURES=native-auth to use this storage mechanism.
","path":["Concepts","Authentication","HTTP credentials"],"tags":[]},{"location":"concepts/authentication/http/#keyring-providers","level":2,"title":"Keyring providers","text":"A keyring provider is a concept from pip allowing retrieval of credentials from an interface matching the popular keyring Python package.
The \"subprocess\" keyring provider invokes the keyring command to fetch credentials. uv does not support additional keyring provider types at this time.
Set --keyring-provider subprocess, UV_KEYRING_PROVIDER=subprocess, or tool.uv.keyring-provider = \"subprocess\" to use the provider.
","path":["Concepts","Authentication","HTTP credentials"],"tags":[]},{"location":"concepts/authentication/http/#persistence-of-credentials","level":2,"title":"Persistence of credentials","text":"If authentication is found for a single index URL or net location (scheme, host, and port), it will be cached for the duration of the command and used for other queries to that index or net location. Authentication is not cached across invocations of uv.
When using uv add, uv will not persist index credentials to the pyproject.toml or uv.lock. These files are often included in source control and distributions, so it is generally unsafe to include credentials in them. However, uv will persist credentials for direct URLs, i.e., package @ https://username:password:example.com/foo.whl, as there is not currently a way to otherwise provide those credentials.
If credentials were attached to an index URL during uv add, uv may fail to fetch dependencies from indexes which require authentication on subsequent operations. See the index authentication documentation for details on persistent authentication for indexes.
","path":["Concepts","Authentication","HTTP credentials"],"tags":[]},{"location":"concepts/authentication/http/#learn-more","level":2,"title":"Learn more","text":"See the index authentication documentation for details on authenticating index URLs.
See the pip compatibility guide for details on differences from pip.
","path":["Concepts","Authentication","HTTP credentials"],"tags":[]},{"location":"concepts/authentication/third-party/","level":1,"title":"Third-party services","text":"","path":["Concepts","Authentication","Third-party services"],"tags":[]},{"location":"concepts/authentication/third-party/#authentication-with-alternative-package-indexes","level":2,"title":"Authentication with alternative package indexes","text":"See the alternative indexes integration guide for details on authentication with popular alternative Python package indexes.
","path":["Concepts","Authentication","Third-party services"],"tags":[]},{"location":"concepts/authentication/third-party/#hugging-face-support","level":2,"title":"Hugging Face support","text":"uv supports automatic authentication for the Hugging Face Hub. Specifically, if the HF_TOKEN environment variable is set, uv will propagate it to requests to huggingface.co.
This is particularly useful for accessing private scripts in Hugging Face Datasets. For example, you can run the following command to execute the script main.py script from a private dataset:
$ HF_TOKEN=hf_... uv run https://huggingface.co/datasets/<user>/<name>/resolve/<branch>/main.py\n
You can disable automatic Hugging Face authentication by setting the UV_NO_HF_TOKEN=1 environment variable.
","path":["Concepts","Authentication","Third-party services"],"tags":[]},{"location":"concepts/projects/","level":1,"title":"Projects","text":"Projects help manage Python code spanning multiple files.
Tip
Looking for an introduction to creating a project with uv? See the projects guide first.
Working on projects is a core part of the uv experience. Learn more about using projects:
- Understanding project structure and files
- Creating new projects
- Managing project dependencies
- Running commands and scripts in a project
- Using lockfiles and syncing the environment
- Configuring the project for advanced use cases
- Building distributions to publish a project
- Using workspaces to work on multiple projects at once
","path":["Concepts","Projects"],"tags":[]},{"location":"concepts/projects/build/","level":1,"title":"Building distributions","text":"To distribute your project to others (e.g., to upload it to an index like PyPI), you'll need to build it into a distributable format.
Python projects are typically distributed as both source distributions (sdists) and binary distributions (wheels). The former is typically a .tar.gz or .zip file containing the project's source code along with some additional metadata, while the latter is a .whl file containing pre-built artifacts that can be installed directly.
Important
When using uv build, uv acts as a build frontend and only determines the Python version to use and invokes the build backend. The details of the builds, such as the included files and the distribution filenames, are determined by the build backend, as defined in [build-system]. Information about build configuration can be found in the respective tool's documentation.
","path":["Concepts","Projects","Building distributions"],"tags":[]},{"location":"concepts/projects/build/#using-uv-build","level":2,"title":"Using uv build","text":"uv build can be used to build both source distributions and binary distributions for your project. By default, uv build will build the project in the current directory, and place the built artifacts in a dist/ subdirectory:
$ uv build\n$ ls dist/\nexample-0.1.0-py3-none-any.whl\nexample-0.1.0.tar.gz\n
You can build the project in a different directory by providing a path to uv build, e.g., uv build path/to/project.
uv build will first build a source distribution, and then build a binary distribution (wheel) from that source distribution.
You can limit uv build to building a source distribution with uv build --sdist, a binary distribution with uv build --wheel, or build both distributions from source with uv build --sdist --wheel.
","path":["Concepts","Projects","Building distributions"],"tags":[]},{"location":"concepts/projects/build/#build-constraints","level":2,"title":"Build constraints","text":"uv build accepts --build-constraint, which can be used to constrain the versions of any build requirements during the build process. When coupled with --require-hashes, uv will enforce that the requirement used to build the project match specific, known hashes, for reproducibility.
For example, given the following constraints.txt:
setuptools==68.2.2 --hash=sha256:b454a35605876da60632df1a60f736524eb73cc47bbc9f3f1ef1b644de74fd2a\n
Running the following would build the project with the specified version of setuptools, and verify that the downloaded setuptools distribution matches the specified hash:
$ uv build --build-constraint constraints.txt --require-hashes\n
","path":["Concepts","Projects","Building distributions"],"tags":[]},{"location":"concepts/projects/config/","level":1,"title":"Configuring projects","text":"","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#python-version-requirement","level":2,"title":"Python version requirement","text":"Projects may declare the Python versions supported by the project in the project.requires-python field of the pyproject.toml.
It is recommended to set a requires-python value:
pyproject.toml[project]\nname = \"example\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12\"\n
The Python version requirement determines the Python syntax that is allowed in the project and affects selection of dependency versions (they must support the same Python version range).
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#entry-points","level":2,"title":"Entry points","text":"Entry points are the official term for an installed package to advertise interfaces. These include:
- Command line interfaces
- Graphical user interfaces
- Plugin entry points
Important
Using the entry point tables requires a build system to be defined.
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#command-line-interfaces","level":3,"title":"Command-line interfaces","text":"Projects may define command line interfaces (CLIs) for the project in the [project.scripts] table of the pyproject.toml.
For example, to declare a command called hello that invokes the hello function in the example module:
pyproject.toml[project.scripts]\nhello = \"example:hello\"\n
Then, the command can be run from a console:
$ uv run hello\n
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#graphical-user-interfaces","level":3,"title":"Graphical user interfaces","text":"Projects may define graphical user interfaces (GUIs) for the project in the [project.gui-scripts] table of the pyproject.toml.
Important
These are only different from command-line interfaces on Windows, where they are wrapped by a GUI executable so they can be started without a console. On other platforms, they behave the same.
For example, to declare a command called hello that invokes the app function in the example module:
pyproject.toml[project.gui-scripts]\nhello = \"example:app\"\n
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#plugin-entry-points","level":3,"title":"Plugin entry points","text":"Projects may define entry points for plugin discovery in the [project.entry-points] table of the pyproject.toml.
For example, to register the example-plugin-a package as a plugin for example:
pyproject.toml[project.entry-points.'example.plugins']\na = \"example_plugin_a\"\n
Then, in example, plugins would be loaded with:
example/__init__.pyfrom importlib.metadata import entry_points\n\nfor plugin in entry_points(group='example.plugins'):\n plugin.load()\n
Note
The group key can be an arbitrary value, it does not need to include the package name or \"plugins\". However, it is recommended to namespace the key by the package name to avoid collisions with other packages.
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#build-systems","level":2,"title":"Build systems","text":"A build system determines how the project should be packaged and installed. Projects may declare and configure a build system in the [build-system] table of the pyproject.toml.
uv uses the presence of a build system to determine if a project contains a package that should be installed in the project virtual environment. If a build system is not defined, uv will not attempt to build or install the project itself, just its dependencies. If a build system is defined, uv will build and install the project into the project environment.
The --build-backend option can be provided to uv init to create a packaged project with an appropriate layout. The --package option can be provided to uv init to create a packaged project with the default build system.
Note
While uv will not build and install the current project without a build system definition, the presence of a [build-system] table is not required in other packages. For legacy reasons, if a build system is not defined, then setuptools.build_meta:__legacy__ is used to build the package. Packages you depend on may not explicitly declare their build system but are still installable. Similarly, if you add a dependency on a local project or install it with uv pip, uv will attempt to build and install it regardless of the presence of a [build-system] table.
Build systems are used to power the following features:
- Including or excluding files from distributions
- Editable installation behavior
- Dynamic project metadata
- Compilation of native code
- Vendoring shared libraries
To configure these features, refer to the documentation of your chosen build system.
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#project-packaging","level":2,"title":"Project packaging","text":"As discussed in build systems, a Python project must be built to be installed. This process is generally referred to as \"packaging\".
You probably need a package if you want to:
- Add commands to the project
- Distribute the project to others
- Use a
src and test layout - Write a library
You probably do not need a package if you are:
- Writing scripts
- Building a simple application
- Using a flat layout
While uv usually uses the declaration of a build system to determine if a project should be packaged, uv also allows overriding this behavior with the tool.uv.package setting.
Setting tool.uv.package = true will force a project to be built and installed into the project environment. If no build system is defined, uv will use the setuptools legacy backend.
Setting tool.uv.package = false will force a project package not to be built and installed into the project environment. uv will ignore a declared build system when interacting with the project; however, uv will still respect explicit attempts to build the project such as invoking uv build.
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#project-environment-path","level":2,"title":"Project environment path","text":"The UV_PROJECT_ENVIRONMENT environment variable can be used to configure the project virtual environment path (.venv by default).
If a relative path is provided, it will be resolved relative to the workspace root. If an absolute path is provided, it will be used as-is, i.e., a child directory will not be created for the environment. If an environment is not present at the provided path, uv will create it.
This option can be used to write to the system Python environment, though it is not recommended. uv sync will remove extraneous packages from the environment by default and, as such, may leave the system in a broken state.
To target the system environment, set UV_PROJECT_ENVIRONMENT to the prefix of the Python installation. For example, on Debian-based systems, this is usually /usr/local:
$ python -c \"import sysconfig; print(sysconfig.get_config_var('prefix'))\"\n/usr/local\n
To target this environment, you'd export UV_PROJECT_ENVIRONMENT=/usr/local.
Important
If an absolute path is provided and the setting is used across multiple projects, the environment will be overwritten by invocations in each project. This setting is only recommended for use for a single project in CI or Docker images.
Note
By default, uv does not read the VIRTUAL_ENV environment variable during project operations. A warning will be displayed if VIRTUAL_ENV is set to a different path than the project's environment. The --active flag can be used to opt-in to respecting VIRTUAL_ENV. The --no-active flag can be used to silence the warning.
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#build-isolation","level":2,"title":"Build isolation","text":"By default, uv builds all packages in isolated virtual environments alongside their declared build dependencies, as per PEP 517.
Some packages are incompatible with this approach to build isolation, be it intentionally or unintentionally.
For example, packages like flash-attn and deepspeed need to build against the same version of PyTorch that is installed in the project environment; by building them in an isolated environment, they may inadvertently build against a different version of PyTorch, leading to runtime errors.
In other cases, packages may accidentally omit necessary dependencies in their declared build dependency list. For example, cchardet requires cython to be installed in the project environment prior to installing cchardet, but does not declare it as a build dependency.
To address these issues, uv supports two separate approaches to modifying the build isolation behavior:
-
Augmenting the list of build dependencies: This allows you to install a package in an isolated environment, but with additional build dependencies that are not declared by the package itself via the extra-build-dependencies setting. For packages like flash-attn, you can even enforce that those build dependencies (like torch) match the version of the package that is or will be installed in the project environment.
-
Disabling build isolation for specific packages: This allows you to install a package without building it in an isolated environment.
When possible, we recommend augmenting the build dependencies rather than disabling build isolation entirely, as the latter approach requires that the build dependencies are installed in the project environment prior to installing the package itself, which can lead to more complex installation steps, the inclusion of extraneous packages in the project environment, and difficulty in reproducing the project environment in other contexts.
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#augmenting-build-dependencies","level":3,"title":"Augmenting build dependencies","text":"To augment the list of build dependencies for a specific package, add it to the extra-build-dependencies list in your pyproject.toml.
For example, to build cchardet with cython as an additional build dependency, include the following in your pyproject.toml:
pyproject.toml[project]\nname = \"project\"\nversion = \"0.1.0\"\ndescription = \"...\"\nreadme = \"README.md\"\nrequires-python = \">=3.12\"\ndependencies = [\"cchardet\"]\n\n[tool.uv.extra-build-dependencies]\ncchardet = [\"cython\"]\n
To ensure that a build dependency matches the version of the package that is or will be installed in the project environment, set match-runtime = true in the extra-build-dependencies table. For example, to build deepspeed with torch as an additional build dependency, include the following in your pyproject.toml:
pyproject.toml[project]\nname = \"project\"\nversion = \"0.1.0\"\ndescription = \"...\"\nreadme = \"README.md\"\nrequires-python = \">=3.12\"\ndependencies = [\"deepspeed\", \"torch\"]\n\n[tool.uv.extra-build-dependencies]\ndeepspeed = [{ requirement = \"torch\", match-runtime = true }]\n
This will ensure that deepspeed is built with the same version of torch that is installed in the project environment.
Similarly, to build flash-attn with torch as an additional build dependency, include the following in your pyproject.toml:
pyproject.toml[project]\nname = \"project\"\nversion = \"0.1.0\"\ndescription = \"...\"\nreadme = \"README.md\"\nrequires-python = \">=3.12\"\ndependencies = [\"flash-attn\", \"torch\"]\n\n[tool.uv.extra-build-dependencies]\nflash-attn = [{ requirement = \"torch\", match-runtime = true }]\n\n[tool.uv.extra-build-variables]\nflash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = \"TRUE\" }\n
Note
The FLASH_ATTENTION_SKIP_CUDA_BUILD environment variable ensures that flash-attn is installed from a compatible, pre-built wheel, rather than attempting to build it from source, which requires access to the CUDA development toolkit. If the CUDA toolkit is not available, the environment variable can be omitted, and flash-attn will be installed from a pre-built wheel if one is available for the current platform, Python version, and PyTorch version.
Similarly, deep_gemm follows the same pattern:
pyproject.toml[project]\nname = \"project\"\nversion = \"0.1.0\"\ndescription = \"...\"\nreadme = \"README.md\"\nrequires-python = \">=3.12\"\ndependencies = [\"deep_gemm\", \"torch\"]\n\n[tool.uv.sources]\ndeep_gemm = { git = \"https://github.com/deepseek-ai/DeepGEMM\" }\n\n[tool.uv.extra-build-dependencies]\ndeep_gemm = [{ requirement = \"torch\", match-runtime = true }]\n
The use of extra-build-dependencies and extra-build-variables are tracked in the uv cache, such that changes to these settings will trigger a reinstall and rebuild of the affected packages. For example, in the case of flash-attn, upgrading the version of torch used in your project would subsequently trigger a rebuild of flash-attn with the new version of torch.
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#dynamic-metadata","level":4,"title":"Dynamic metadata","text":"The use of match-runtime = true is only available for packages like flash-attn that declare static metadata. If static metadata is unavailable, uv is required to build the package during the dependency resolution phase; as such, uv cannot determine the version of the build dependency that would ultimately be installed in the project environment.
In other words, if flash-attn did not declare static metadata, uv would not be able to determine the version of torch that would be installed in the project environment, since it would need to build flash-attn prior to resolving the torch version.
As a concrete example, axolotl is a popular package that requires augmented build dependencies, but does not declare static metadata, as the package's dependencies vary based on the version of torch that is installed in the project environment. In this case, users should instead specify the exact version of torch that they intend to use in their project, and then augment the build dependencies with that version.
For example, to build axolotl against torch==2.6.0, include the following in your pyproject.toml:
pyproject.toml[project]\nname = \"project\"\nversion = \"0.1.0\"\ndescription = \"...\"\nreadme = \"README.md\"\nrequires-python = \">=3.12\"\ndependencies = [\"axolotl[deepspeed, flash-attn]\", \"torch==2.6.0\"]\n\n[tool.uv.extra-build-dependencies]\naxolotl = [\"torch==2.6.0\"]\ndeepspeed = [\"torch==2.6.0\"]\nflash-attn = [\"torch==2.6.0\"]\n
Similarly, older versions of flash-attn did not declare static metadata, and thus would not have supported match-runtime = true out of the box. Unlike axolotl, though, flash-attn did not vary its dependencies based on dynamic properties of the build environment. As such, users could instead provide the flash-attn metadata upfront via the dependency-metadata setting, thereby forgoing the need to build the package during the dependency resolution phase. For example, to provide the flash-attn metadata upfront:
pyproject.toml[[tool.uv.dependency-metadata]]\nname = \"flash-attn\"\nversion = \"2.6.3\"\nrequires-dist = [\"torch\", \"einops\"]\n
Tip
To determine the package metadata for a package like flash-attn, navigate to the appropriate Git repository, or look it up on PyPI and download the package's source distribution. The package requirements can typically be found in the setup.py or setup.cfg file.
(If the package includes a built distribution, you can unzip it to find the METADATA file; however, the presence of a built distribution would negate the need to provide the metadata upfront, since it would already be available to uv.)
The version field in tool.uv.dependency-metadata is optional for registry-based dependencies (when omitted, uv will assume the metadata applies to all versions of the package), but required for direct URL dependencies (like Git dependencies).
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#disabling-build-isolation","level":3,"title":"Disabling build isolation","text":"Installing packages without build isolation requires that the package's build dependencies are installed in the project environment prior to building the package itself.
For example, historically, to install cchardet without build isolation, you would first need to install the cython and setuptools packages in the project environment, followed by a separate invocation to install cchardet without build isolation:
$ uv venv\n$ uv pip install cython setuptools\n$ uv pip install cchardet --no-build-isolation\n
uv simplifies this process by allowing you to specify packages that should not be built in isolation via the no-build-isolation-package setting in your pyproject.toml and the --no-build-isolation-package flag in the command line. Further, when a package is marked for disabling build isolation, uv will perform a two-phase install, first installing any packages that support build isolation, followed by those that do not. As a result, if a project's build dependencies are included as project dependencies, uv will automatically install them before installing the package that requires build isolation to be disabled.
For example, to install cchardet without build isolation, include the following in your pyproject.toml:
pyproject.toml[project]\nname = \"project\"\nversion = \"0.1.0\"\ndescription = \"...\"\nreadme = \"README.md\"\nrequires-python = \">=3.12\"\ndependencies = [\"cchardet\", \"cython\", \"setuptools\"]\n\n[tool.uv]\nno-build-isolation-package = [\"cchardet\"]\n
When running uv sync, uv will first install cython and setuptools in the project environment, followed by cchardet (without build isolation):
$ uv sync --extra build\n + cchardet==2.1.7\n + cython==3.1.3\n + setuptools==80.9.0\n
Similarly, to install flash-attn without build isolation, include the following in your pyproject.toml:
pyproject.toml[project]\nname = \"project\"\nversion = \"0.1.0\"\ndescription = \"...\"\nreadme = \"README.md\"\nrequires-python = \">=3.12\"\ndependencies = [\"flash-attn\", \"torch\"]\n\n[tool.uv]\nno-build-isolation-package = [\"flash-attn\"]\n
When running uv sync, uv will first install torch in the project environment, followed by flash-attn (without build isolation). As torch is both a project dependency and a build dependency, the version of torch is guaranteed to be consistent between the build and runtime environments.
A downside of the above approach is that it requires the build dependencies to be installed in the project environment, which is appropriate for flash-attn (which requires torch both at build-time and runtime), but not for cchardet (which only requires cython at build-time).
To avoid including build dependencies in the project environment, uv supports a two-step installation process that allows you to separate the build dependencies from the packages that require them.
For example, the build dependencies for cchardet can be isolated to an optional build group, as in:
pyproject.toml[project]\nname = \"project\"\nversion = \"0.1.0\"\ndescription = \"...\"\nreadme = \"README.md\"\nrequires-python = \">=3.12\"\ndependencies = [\"cchardet\"]\n\n[project.optional-dependencies]\nbuild = [\"setuptools\", \"cython\"]\n\n[tool.uv]\nno-build-isolation-package = [\"cchardet\"]\n
Given the above, a user would first sync with the build optional group, and then without it to remove the build dependencies:
$ uv sync --extra build\n + cchardet==2.1.7\n + cython==3.1.3\n + setuptools==80.9.0\n$ uv sync\n - cython==3.1.3\n - setuptools==80.9.0\n
Some packages, like cchardet, only require build dependencies for the installation phase of uv sync. Others require their build dependencies to be present even just to resolve the project's dependencies during the resolution phase.
In such cases, the build dependencies can be installed prior to running any uv lock or uv sync commands, using the lower lower-level uv pip API. For example, given:
pyproject.toml[project]\nname = \"project\"\nversion = \"0.1.0\"\ndescription = \"...\"\nreadme = \"README.md\"\nrequires-python = \">=3.12\"\ndependencies = [\"flash-attn\"]\n\n[tool.uv]\nno-build-isolation-package = [\"flash-attn\"]\n
You could run the following sequence of commands to sync flash-attn:
$ uv venv\n$ uv pip install torch setuptools\n$ uv sync\n
Alternatively, users can instead provide the flash-attn metadata upfront via the dependency-metadata setting, thereby forgoing the need to build the package during the dependency resolution phase. For example, to provide the flash-attn metadata upfront:
pyproject.toml[[tool.uv.dependency-metadata]]\nname = \"flash-attn\"\nversion = \"2.6.3\"\nrequires-dist = [\"torch\", \"einops\"]\n
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#editable-mode","level":2,"title":"Editable mode","text":"By default, the project will be installed in editable mode, such that changes to the source code are immediately reflected in the environment. uv sync and uv run both accept a --no-editable flag, which instructs uv to install the project in non-editable mode. --no-editable is intended for deployment use-cases, such as building a Docker container, in which the project should be included in the deployed environment without a dependency on the originating source code.
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#conflicting-dependencies","level":2,"title":"Conflicting dependencies","text":"uv resolves all project dependencies together, including optional dependencies (\"extras\") and dependency groups. If dependencies declared in one section are not compatible with those in another section, uv will fail to resolve the requirements of the project with an error.
uv supports explicit declaration of conflicting dependency groups. For example, to declare that the optional-dependency groups extra1 and extra2 are incompatible:
pyproject.toml[tool.uv]\nconflicts = [\n [\n { extra = \"extra1\" },\n { extra = \"extra2\" },\n ],\n]\n
Or, to declare the development dependency groups group1 and group2 incompatible:
pyproject.toml[tool.uv]\nconflicts = [\n [\n { group = \"group1\" },\n { group = \"group2\" },\n ],\n]\n
See the resolution documentation for more.
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#limited-resolution-environments","level":2,"title":"Limited resolution environments","text":"If your project supports a more limited set of platforms or Python versions, you can constrain the set of solved platforms via the environments setting, which accepts a list of PEP 508 environment markers. For example, to constrain the lockfile to macOS and Linux, and exclude Windows:
pyproject.toml[tool.uv]\nenvironments = [\n \"sys_platform == 'darwin'\",\n \"sys_platform == 'linux'\",\n]\n
See the resolution documentation for more.
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/config/#required-environments","level":2,"title":"Required environments","text":"If your project must support a specific platform or Python version, you can mark that platform as required via the required-environments setting. For example, to require that the project supports Intel macOS:
pyproject.toml[tool.uv]\nrequired-environments = [\n \"sys_platform == 'darwin' and platform_machine == 'x86_64'\",\n]\n
The required-environments setting is only relevant for packages that do not publish a source distribution (like PyTorch), as such packages can only be installed on environments covered by the set of pre-built binary distributions (wheels) published by that package.
See the resolution documentation for more.
","path":["Concepts","Projects","Configuring projects"],"tags":[]},{"location":"concepts/projects/dependencies/","level":1,"title":"Managing dependencies","text":"","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#dependency-fields","level":2,"title":"Dependency fields","text":"Dependencies of the project are defined in several fields:
project.dependencies: Published dependencies.project.optional-dependencies: Published optional dependencies, or \"extras\".dependency-groups: Local dependencies for development.tool.uv.sources: Alternative sources for dependencies during development.
Note
The project.dependencies and project.optional-dependencies fields can be used even if project isn't going to be published. dependency-groups are a recently standardized feature and may not be supported by all tools yet.
uv supports modifying the project's dependencies with uv add and uv remove, but dependency metadata can also be updated by editing the pyproject.toml directly.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#adding-dependencies","level":2,"title":"Adding dependencies","text":"To add a dependency:
$ uv add httpx\n
An entry will be added in the project.dependencies field:
pyproject.toml[project]\nname = \"example\"\nversion = \"0.1.0\"\ndependencies = [\"httpx>=0.27.2\"]\n
The --dev, --group, or --optional flags can be used to add dependencies to an alternative field.
The dependency will include a constraint, e.g., >=0.27.2, for the most recent, compatible version of the package. The kind of bound can be adjusted with --bounds, or the constraint can be provided directly:
$ uv add \"httpx>=0.20\"\n
When adding a dependency from a source other than a package registry, uv will add an entry in the sources field. For example, when adding httpx from GitHub:
$ uv add \"httpx @ git+https://github.com/encode/httpx\"\n
The pyproject.toml will include a Git source entry:
pyproject.toml[project]\nname = \"example\"\nversion = \"0.1.0\"\ndependencies = [\n \"httpx\",\n]\n\n[tool.uv.sources]\nhttpx = { git = \"https://github.com/encode/httpx\" }\n
If a dependency cannot be used, uv will display an error.:
$ uv add \"httpx>9999\"\n × No solution found when resolving dependencies:\n ╰─▶ Because only httpx<=1.0.0b0 is available and your project depends on httpx>9999,\n we can conclude that your project's requirements are unsatisfiable.\n
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#importing-dependencies-from-requirements-files","level":3,"title":"Importing dependencies from requirements files","text":"Dependencies declared in a requirements.txt file can be added to the project with the -r option:
uv add -r requirements.txt\n
See the pip migration guide for more details.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#removing-dependencies","level":2,"title":"Removing dependencies","text":"To remove a dependency:
$ uv remove httpx\n
The --dev, --group, or --optional flags can be used to remove a dependency from a specific table.
If a source is defined for the removed dependency, and there are no other references to the dependency, it will also be removed.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#changing-dependencies","level":2,"title":"Changing dependencies","text":"To change an existing dependency, e.g., to use a different constraint for httpx:
$ uv add \"httpx>0.1.0\"\n
Note
In this example, we are changing the constraints for the dependency in the pyproject.toml. The locked version of the dependency will only change if necessary to satisfy the new constraints. To force the package version to update to the latest within the constraints, use --upgrade-package <name>, e.g.:
$ uv add \"httpx>0.1.0\" --upgrade-package httpx\n
See the lockfile documentation for more details on upgrading packages.
Requesting a different dependency source will update the tool.uv.sources table, e.g., to use httpx from a local path during development:
$ uv add \"httpx @ ../httpx\"\n
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#platform-specific-dependencies","level":2,"title":"Platform-specific dependencies","text":"To ensure that a dependency is only installed on a specific platform or on specific Python versions, use environment markers.
For example, to install jax on Linux, but not on Windows or macOS:
$ uv add \"jax; sys_platform == 'linux'\"\n
The resulting pyproject.toml will then include the environment marker in the dependency definition:
pyproject.toml[project]\nname = \"project\"\nversion = \"0.1.0\"\nrequires-python = \">=3.11\"\ndependencies = [\"jax; sys_platform == 'linux'\"]\n
Similarly, to include numpy on Python 3.11 and later:
$ uv add \"numpy; python_version >= '3.11'\"\n
See Python's environment marker documentation for a complete enumeration of the available markers and operators.
Tip
Dependency sources can also be changed per-platform.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#project-dependencies","level":2,"title":"Project dependencies","text":"The project.dependencies table represents the dependencies that are used when uploading to PyPI or building a wheel. Individual dependencies are specified using dependency specifiers syntax, and the table follows the PEP 621 standard.
project.dependencies defines the list of packages that are required for the project, along with the version constraints that should be used when installing them. Each entry includes a dependency name and version. An entry may include extras or environment markers for platform-specific packages. For example:
pyproject.toml[project]\nname = \"albatross\"\nversion = \"0.1.0\"\ndependencies = [\n # Any version in this range\n \"tqdm >=4.66.2,<5\",\n # Exactly this version of torch\n \"torch ==2.2.2\",\n # Install transformers with the torch extra\n \"transformers[torch] >=4.39.3,<5\",\n # Only install this package on older python versions\n # See \"Environment Markers\" for more information\n \"importlib_metadata >=7.1.0,<8; python_version < '3.10'\",\n \"mollymawk ==0.1.0\"\n]\n
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#dependency-sources","level":2,"title":"Dependency sources","text":"The tool.uv.sources table extends the standard dependency tables with alternative dependency sources, which are used during development.
Dependency sources add support for common patterns that are not supported by the project.dependencies standard, like editable installations and relative paths. For example, to install foo from a directory relative to the project root:
pyproject.toml[project]\nname = \"example\"\nversion = \"0.1.0\"\ndependencies = [\"foo\"]\n\n[tool.uv.sources]\nfoo = { path = \"./packages/foo\" }\n
The following dependency sources are supported by uv:
- Index: A package resolved from a specific package index.
- Git: A Git repository.
- URL: A remote wheel or source distribution.
- Path: A local wheel, source distribution, or project directory.
- Workspace: A member of the current workspace.
Important
Sources are only respected by uv. If another tool is used, only the definitions in the standard project tables will be used. If another tool is being used for development, any metadata provided in the source table will need to be re-specified in the other tool's format.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#index","level":3,"title":"Index","text":"To add Python package from a specific index, use the --index option:
$ uv add torch --index pytorch=https://download.pytorch.org/whl/cpu\n
uv will store the index in [[tool.uv.index]] and add a [tool.uv.sources] entry:
pyproject.toml[project]\ndependencies = [\"torch\"]\n\n[tool.uv.sources]\ntorch = { index = \"pytorch\" }\n\n[[tool.uv.index]]\nname = \"pytorch\"\nurl = \"https://download.pytorch.org/whl/cpu\"\n
Tip
The above example will only work on x86-64 Linux, due to the specifics of the PyTorch index. See the PyTorch guide for more information about setting up PyTorch.
Using an index source pins a package to the given index — it will not be downloaded from other indexes.
When defining an index, an explicit flag can be included to indicate that the index should only be used for packages that explicitly specify it in tool.uv.sources. If explicit is not set, other packages may be resolved from the index, if not found elsewhere.
pyproject.toml[[tool.uv.index]]\nname = \"pytorch\"\nurl = \"https://download.pytorch.org/whl/cpu\"\nexplicit = true\n
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#git","level":3,"title":"Git","text":"To add a Git dependency source, prefix a Git-compatible URL with git+.
For example:
$ # Install over HTTP(S).\n$ uv add git+https://github.com/encode/httpx\n\n$ # Install over SSH.\n$ uv add git+ssh://git@github.com/encode/httpx\n
pyproject.toml[project]\ndependencies = [\"httpx\"]\n\n[tool.uv.sources]\nhttpx = { git = \"https://github.com/encode/httpx\" }\n
Specific Git references can be requested, e.g., a tag:
$ uv add git+https://github.com/encode/httpx --tag 0.27.0\n
pyproject.toml[project]\ndependencies = [\"httpx\"]\n\n[tool.uv.sources]\nhttpx = { git = \"https://github.com/encode/httpx\", tag = \"0.27.0\" }\n
Or, a branch:
$ uv add git+https://github.com/encode/httpx --branch main\n
pyproject.toml[project]\ndependencies = [\"httpx\"]\n\n[tool.uv.sources]\nhttpx = { git = \"https://github.com/encode/httpx\", branch = \"main\" }\n
Or, a revision (commit):
$ uv add git+https://github.com/encode/httpx --rev 326b9431c761e1ef1e00b9f760d1f654c8db48c6\n
pyproject.toml[project]\ndependencies = [\"httpx\"]\n\n[tool.uv.sources]\nhttpx = { git = \"https://github.com/encode/httpx\", rev = \"326b9431c761e1ef1e00b9f760d1f654c8db48c6\" }\n
A subdirectory may be specified if the package isn't in the repository root:
$ uv add git+https://github.com/langchain-ai/langchain#subdirectory=libs/langchain\n
pyproject.toml[project]\ndependencies = [\"langchain\"]\n\n[tool.uv.sources]\nlangchain = { git = \"https://github.com/langchain-ai/langchain\", subdirectory = \"libs/langchain\" }\n
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#url","level":3,"title":"URL","text":"To add a URL source, provide a https:// URL to either a wheel (ending in .whl) or a source distribution (typically ending in .tar.gz or .zip; see here for all supported formats).
For example:
$ uv add \"https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz\"\n
Will result in a pyproject.toml with:
pyproject.toml[project]\ndependencies = [\"httpx\"]\n\n[tool.uv.sources]\nhttpx = { url = \"https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz\" }\n
URL dependencies can also be manually added or edited in the pyproject.toml with the { url = <url> } syntax. A subdirectory may be specified if the source distribution isn't in the archive root.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#path","level":3,"title":"Path","text":"To add a path source, provide the path of a wheel (ending in .whl), a source distribution (typically ending in .tar.gz or .zip; see here for all supported formats), or a directory containing a pyproject.toml.
For example:
$ uv add /example/foo-0.1.0-py3-none-any.whl\n
Will result in a pyproject.toml with:
pyproject.toml[project]\ndependencies = [\"foo\"]\n\n[tool.uv.sources]\nfoo = { path = \"/example/foo-0.1.0-py3-none-any.whl\" }\n
The path may also be a relative path:
$ uv add ./foo-0.1.0-py3-none-any.whl\n
Or, a path to a project directory:
$ uv add ~/projects/bar/\n
Important
When using a directory as a path dependency, uv will attempt to build and install the target as a package by default. See the virtual dependency documentation for details.
An editable installation is not used for path dependencies by default. An editable installation may be requested for project directories:
$ uv add --editable ../projects/bar/\n
Which will result in a pyproject.toml with:
pyproject.toml[project]\ndependencies = [\"bar\"]\n\n[tool.uv.sources]\nbar = { path = \"../projects/bar\", editable = true }\n
Tip
For multiple packages in the same repository, workspaces may be a better fit.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#workspace-member","level":3,"title":"Workspace member","text":"To declare a dependency on a workspace member, add the member name with { workspace = true }. All workspace members must be explicitly stated. Workspace members are always editable . See the workspace documentation for more details on workspaces.
pyproject.toml[project]\ndependencies = [\"foo==0.1.0\"]\n\n[tool.uv.sources]\nfoo = { workspace = true }\n\n[tool.uv.workspace]\nmembers = [\n \"packages/foo\"\n]\n
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#platform-specific-sources","level":3,"title":"Platform-specific sources","text":"You can limit a source to a given platform or Python version by providing dependency specifiers-compatible environment markers for the source.
For example, to pull httpx from GitHub, but only on macOS, use the following:
pyproject.toml[project]\ndependencies = [\"httpx\"]\n\n[tool.uv.sources]\nhttpx = { git = \"https://github.com/encode/httpx\", tag = \"0.27.2\", marker = \"sys_platform == 'darwin'\" }\n
By specifying the marker on the source, uv will still include httpx on all platforms, but will download the source from GitHub on macOS, and fall back to PyPI on all other platforms.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#multiple-sources","level":3,"title":"Multiple sources","text":"You can specify multiple sources for a single dependency by providing a list of sources, disambiguated by PEP 508-compatible environment markers.
For example, to pull in different httpx tags on macOS vs. Linux:
pyproject.toml[project]\ndependencies = [\"httpx\"]\n\n[tool.uv.sources]\nhttpx = [\n { git = \"https://github.com/encode/httpx\", tag = \"0.27.2\", marker = \"sys_platform == 'darwin'\" },\n { git = \"https://github.com/encode/httpx\", tag = \"0.24.1\", marker = \"sys_platform == 'linux'\" },\n]\n
This strategy extends to using different indexes based on environment markers. For example, to install torch from different PyTorch indexes based on the platform:
pyproject.toml[project]\ndependencies = [\"torch\"]\n\n[tool.uv.sources]\ntorch = [\n { index = \"torch-cpu\", marker = \"platform_system == 'Darwin'\"},\n { index = \"torch-gpu\", marker = \"platform_system == 'Linux'\"},\n]\n\n[[tool.uv.index]]\nname = \"torch-cpu\"\nurl = \"https://download.pytorch.org/whl/cpu\"\nexplicit = true\n\n[[tool.uv.index]]\nname = \"torch-gpu\"\nurl = \"https://download.pytorch.org/whl/cu124\"\nexplicit = true\n
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#disabling-sources","level":3,"title":"Disabling sources","text":"To instruct uv to ignore the tool.uv.sources table (e.g., to simulate resolving with the package's published metadata), use the --no-sources flag:
$ uv lock --no-sources\n
The use of --no-sources will also prevent uv from discovering any workspace members that could satisfy a given dependency.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#optional-dependencies","level":2,"title":"Optional dependencies","text":"It is common for projects that are published as libraries to make some features optional to reduce the default dependency tree. For example, Pandas has an excel extra and a plot extra to avoid installation of Excel parsers and matplotlib unless someone explicitly requires them. Extras are requested with the package[<extra>] syntax, e.g., pandas[plot, excel].
Optional dependencies are specified in [project.optional-dependencies], a TOML table that maps from extra name to its dependencies, following dependency specifiers syntax.
Optional dependencies can have entries in tool.uv.sources the same as normal dependencies.
pyproject.toml[project]\nname = \"pandas\"\nversion = \"1.0.0\"\n\n[project.optional-dependencies]\nplot = [\n \"matplotlib>=3.6.3\"\n]\nexcel = [\n \"odfpy>=1.4.1\",\n \"openpyxl>=3.1.0\",\n \"python-calamine>=0.1.7\",\n \"pyxlsb>=1.0.10\",\n \"xlrd>=2.0.1\",\n \"xlsxwriter>=3.0.5\"\n]\n
To add an optional dependency, use the --optional <extra> option:
$ uv add httpx --optional network\n
Note
If you have optional dependencies that conflict with one another, resolution will fail unless you explicitly declare them as conflicting.
Sources can also be declared as applying only to a specific optional dependency. For example, to pull torch from different PyTorch indexes based on an optional cpu or gpu extra:
pyproject.toml[project]\ndependencies = []\n\n[project.optional-dependencies]\ncpu = [\n \"torch\",\n]\ngpu = [\n \"torch\",\n]\n\n[tool.uv.sources]\ntorch = [\n { index = \"torch-cpu\", extra = \"cpu\" },\n { index = \"torch-gpu\", extra = \"gpu\" },\n]\n\n[[tool.uv.index]]\nname = \"torch-cpu\"\nurl = \"https://download.pytorch.org/whl/cpu\"\n\n[[tool.uv.index]]\nname = \"torch-gpu\"\nurl = \"https://download.pytorch.org/whl/cu124\"\n
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#development-dependencies","level":2,"title":"Development dependencies","text":"Unlike optional dependencies, development dependencies are local-only and will not be included in the project requirements when published to PyPI or other indexes. As such, development dependencies are not included in the [project] table.
Development dependencies can have entries in tool.uv.sources the same as normal dependencies.
To add a development dependency, use the --dev flag:
$ uv add --dev pytest\n
uv uses the [dependency-groups] table (as defined in PEP 735) for declaration of development dependencies. The above command will create a dev group:
pyproject.toml[dependency-groups]\ndev = [\n \"pytest >=8.1.1,<9\"\n]\n
The dev group is special-cased; there are --dev, --only-dev, and --no-dev flags to toggle inclusion or exclusion of its dependencies. See --no-default-groups to disable all default groups instead. Additionally, the dev group is synced by default.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#dependency-groups","level":3,"title":"Dependency groups","text":"Development dependencies can be divided into multiple groups, using the --group flag.
For example, to add a development dependency in the lint group:
$ uv add --group lint ruff\n
Which results in the following [dependency-groups] definition:
pyproject.toml[dependency-groups]\ndev = [\n \"pytest\"\n]\nlint = [\n \"ruff\"\n]\n
Once groups are defined, the --all-groups, --no-default-groups, --group, --only-group, and --no-group options can be used to include or exclude their dependencies.
Tip
The --dev, --only-dev, and --no-dev flags are equivalent to --group dev, --only-group dev, and --no-group dev respectively.
uv requires that all dependency groups are compatible with each other and resolves all groups together when creating the lockfile.
If dependencies declared in one group are not compatible with those in another group, uv will fail to resolve the requirements of the project with an error.
Note
If you have dependency groups that conflict with one another, resolution will fail unless you explicitly declare them as conflicting.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#nesting-groups","level":3,"title":"Nesting groups","text":"A dependency group can include other dependency groups, e.g.:
pyproject.toml[dependency-groups]\ndev = [\n {include-group = \"lint\"},\n {include-group = \"test\"}\n]\nlint = [\n \"ruff\"\n]\ntest = [\n \"pytest\"\n]\n
An included group's dependencies cannot conflict with the other dependencies declared in a group.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#default-groups","level":3,"title":"Default groups","text":"By default, uv includes the dev dependency group in the environment (e.g., during uv run or uv sync). The default groups to include can be changed using the tool.uv.default-groups setting.
pyproject.toml[tool.uv]\ndefault-groups = [\"dev\", \"foo\"]\n
To enable all dependencies groups by default, use \"all\" instead of listing group names:
pyproject.toml[tool.uv]\ndefault-groups = \"all\"\n
Tip
To disable this behaviour during uv run or uv sync, use --no-default-groups. To exclude a specific default group, use --no-group <name>.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#group-requires-python","level":3,"title":"Group requires-python","text":"By default, dependency groups must be compatible with your project's requires-python range.
If a dependency group requires a different range of Python versions than your project, you can specify a requires-python for the group in [tool.uv.dependency-groups], e.g.:
pyproject.toml[project]\nname = \"example\"\nversion = \"0.0.0\"\nrequires-python = \">=3.10\"\n\n[dependency-groups]\ndev = [\"pytest\"]\n\n[tool.uv.dependency-groups]\ndev = {requires-python = \">=3.12\"}\n
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#legacy-dev-dependencies","level":3,"title":"Legacy dev-dependencies","text":"Before [dependency-groups] was standardized, uv used the tool.uv.dev-dependencies field to specify development dependencies, e.g.:
pyproject.toml[tool.uv]\ndev-dependencies = [\n \"pytest\"\n]\n
Dependencies declared in this section will be combined with the contents in the dependency-groups.dev. Eventually, the dev-dependencies field will be deprecated and removed.
Note
If a tool.uv.dev-dependencies field exists, uv add --dev will use the existing section instead of adding a new dependency-groups.dev section.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#build-dependencies","level":2,"title":"Build dependencies","text":"If a project is structured as Python package, it may declare dependencies that are required to build the project, but not required to run it. These dependencies are specified in the [build-system] table under build-system.requires, following PEP 518.
For example, if a project uses setuptools as its build backend, it should declare setuptools as a build dependency:
pyproject.toml[project]\nname = \"pandas\"\nversion = \"0.1.0\"\n\n[build-system]\nrequires = [\"setuptools>=42\"]\nbuild-backend = \"setuptools.build_meta\"\n
By default, uv will respect tool.uv.sources when resolving build dependencies. For example, to use a local version of setuptools for building, add the source to tool.uv.sources:
pyproject.toml[project]\nname = \"pandas\"\nversion = \"0.1.0\"\n\n[build-system]\nrequires = [\"setuptools>=42\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[tool.uv.sources]\nsetuptools = { path = \"./packages/setuptools\" }\n
When publishing a package, we recommend running uv build --no-sources to ensure that the package builds correctly when tool.uv.sources is disabled, as is the case when using other build tools, like pypa/build.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#editable-dependencies","level":2,"title":"Editable dependencies","text":"A regular installation of a directory with a Python package first builds a wheel and then installs that wheel into your virtual environment, copying all source files. When the package source files are edited, the virtual environment will contain outdated versions.
Editable installations solve this problem by adding a link to the project within the virtual environment (a .pth file), which instructs the interpreter to include the source files directly.
There are some limitations to editables (mainly: the build backend needs to support them, and native modules aren't recompiled before import), but they are useful for development, as the virtual environment will always use the latest changes to the package.
uv uses editable installation for workspace packages by default.
To add an editable dependency, use the --editable flag:
$ uv add --editable ./path/foo\n
Or, to opt-out of using an editable dependency in a workspace:
$ uv add --no-editable ./path/foo\n
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#virtual-dependencies","level":2,"title":"Virtual dependencies","text":"uv allows dependencies to be \"virtual\", in which the dependency itself is not installed as a package, but its dependencies are.
By default, dependencies are never virtual.
A dependency with a path source can be virtual if it explicitly sets tool.uv.package = false. Unlike working in the dependent project with uv, the package will be built even if a build system is not declared.
To treat a dependency as virtual, set package = false on the source:
pyproject.toml[project]\ndependencies = [\"bar\"]\n\n[tool.uv.sources]\nbar = { path = \"../projects/bar\", package = false }\n
If a dependency sets tool.uv.package = false, it can be overridden by declaring package = true on the source:
pyproject.toml[project]\ndependencies = [\"bar\"]\n\n[tool.uv.sources]\nbar = { path = \"../projects/bar\", package = true }\n
Similarly, a dependency with a workspace source can be virtual if it explicitly sets tool.uv.package = false. The workspace member will be built even if a build system is not declared.
Workspace members that are not dependencies can be virtual by default, e.g., if the parent pyproject.toml is:
pyproject.toml[project]\nname = \"parent\"\nversion = \"1.0.0\"\ndependencies = []\n\n[tool.uv.workspace]\nmembers = [\"child\"]\n
And the child pyproject.toml excluded a build system:
pyproject.toml[project]\nname = \"child\"\nversion = \"1.0.0\"\ndependencies = [\"anyio\"]\n
Then the child workspace member would not be installed, but the transitive dependency anyio would be.
In contrast, if the parent declared a dependency on child:
pyproject.toml[project]\nname = \"parent\"\nversion = \"1.0.0\"\ndependencies = [\"child\"]\n\n[tool.uv.sources]\nchild = { workspace = true }\n\n[tool.uv.workspace]\nmembers = [\"child\"]\n
Then child would be built and installed.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/dependencies/#dependency-specifiers","level":2,"title":"Dependency specifiers","text":"uv uses standard dependency specifiers, originally defined in PEP 508. A dependency specifier is composed of, in order:
- The dependency name
- The extras you want (optional)
- The version specifier
- An environment marker (optional)
The version specifiers are comma separated and added together, e.g., foo >=1.2.3,<2,!=1.4.0 is interpreted as \"a version of foo that's at least 1.2.3, but less than 2, and not 1.4.0\".
Specifiers are padded with trailing zeros if required, so foo ==2 matches foo 2.0.0, too.
A star can be used for the last digit with equals, e.g., foo ==2.1.* will accept any release from the 2.1 series. Similarly, ~= matches where the last digit is equal or higher, e.g., foo ~=1.2 is equal to foo >=1.2,<2, and foo ~=1.2.3 is equal to foo >=1.2.3,<1.3.
Extras are comma-separated in square bracket between name and version, e.g., pandas[excel,plot] ==2.2. Whitespace between extra names is ignored.
Some dependencies are only required in specific environments, e.g., a specific Python version or operating system. For example to install the importlib-metadata backport for the importlib.metadata module, use importlib-metadata >=7.1.0,<8; python_version < '3.10'. To install colorama on Windows (but omit it on other platforms), use colorama >=0.4.6,<5; platform_system == \"Windows\".
Markers are combined with and, or, and parentheses, e.g., aiohttp >=3.7.4,<4; (sys_platform != 'win32' or implementation_name != 'pypy') and python_version >= '3.10'. Note that versions within markers must be quoted, while versions outside of markers must not be quoted.
","path":["Concepts","Projects","Managing dependencies"],"tags":[]},{"location":"concepts/projects/init/","level":1,"title":"Creating projects","text":"uv supports creating a project with uv init.
When creating projects, uv supports two basic templates: applications and libraries. By default, uv will create a project for an application. The --lib flag can be used to create a project for a library instead.
","path":["Concepts","Projects","Creating projects"],"tags":[]},{"location":"concepts/projects/init/#target-directory","level":2,"title":"Target directory","text":"uv will create a project in the working directory, or, in a target directory by providing a name, e.g., uv init foo. If there's already a project in the target directory, i.e., if there's a pyproject.toml, uv will exit with an error.
","path":["Concepts","Projects","Creating projects"],"tags":[]},{"location":"concepts/projects/init/#applications","level":2,"title":"Applications","text":"Application projects are suitable for web servers, scripts, and command-line interfaces.
Applications are the default target for uv init, but can also be specified with the --app flag.
$ uv init example-app\n
The project includes a pyproject.toml, a sample file (main.py), a readme, and a Python version pin file (.python-version).
$ tree example-app\nexample-app\n├── .python-version\n├── README.md\n├── main.py\n└── pyproject.toml\n
Note
Prior to v0.6.0, uv created a file named hello.py instead of main.py.
The pyproject.toml includes basic metadata. It does not include a build system, it is not a package and will not be installed into the environment:
pyproject.toml[project]\nname = \"example-app\"\nversion = \"0.1.0\"\ndescription = \"Add your description here\"\nreadme = \"README.md\"\nrequires-python = \">=3.11\"\ndependencies = []\n
The sample file defines a main function with some standard boilerplate:
main.pydef main():\n print(\"Hello from example-app!\")\n\n\nif __name__ == \"__main__\":\n main()\n
Python files can be executed with uv run:
$ cd example-app\n$ uv run main.py\nHello from example-project!\n
","path":["Concepts","Projects","Creating projects"],"tags":[]},{"location":"concepts/projects/init/#packaged-applications","level":2,"title":"Packaged applications","text":"Many use-cases require a package. For example, if you are creating a command-line interface that will be published to PyPI or if you want to define tests in a dedicated directory.
The --package flag can be used to create a packaged application:
$ uv init --package example-pkg\n
The source code is moved into a src directory with a module directory and an __init__.py file:
$ tree example-pkg\nexample-pkg\n├── .python-version\n├── README.md\n├── pyproject.toml\n└── src\n └── example_pkg\n └── __init__.py\n
A build system is defined, so the project will be installed into the environment:
pyproject.toml[project]\nname = \"example-pkg\"\nversion = \"0.1.0\"\ndescription = \"Add your description here\"\nreadme = \"README.md\"\nrequires-python = \">=3.11\"\ndependencies = []\n\n[project.scripts]\nexample-pkg = \"example_pkg:main\"\n\n[build-system]\nrequires = [\"uv_build>=0.9.8,<0.10.0\"]\nbuild-backend = \"uv_build\"\n
Tip
The --build-backend option can be used to request an alternative build system.
A command definition is included:
pyproject.toml[project]\nname = \"example-pkg\"\nversion = \"0.1.0\"\ndescription = \"Add your description here\"\nreadme = \"README.md\"\nrequires-python = \">=3.11\"\ndependencies = []\n\n[project.scripts]\nexample-pkg = \"example_pkg:main\"\n\n[build-system]\nrequires = [\"uv_build>=0.9.8,<0.10.0\"]\nbuild-backend = \"uv_build\"\n
The command can be executed with uv run:
$ cd example-pkg\n$ uv run example-pkg\nHello from example-pkg!\n
","path":["Concepts","Projects","Creating projects"],"tags":[]},{"location":"concepts/projects/init/#libraries","level":2,"title":"Libraries","text":"A library provides functions and objects for other projects to consume. Libraries are intended to be built and distributed, e.g., by uploading them to PyPI.
Libraries can be created by using the --lib flag:
$ uv init --lib example-lib\n
Note
Using --lib implies --package. Libraries always require a packaged project.
As with a packaged application, a src layout is used. A py.typed marker is included to indicate to consumers that types can be read from the library:
$ tree example-lib\nexample-lib\n├── .python-version\n├── README.md\n├── pyproject.toml\n└── src\n └── example_lib\n ├── py.typed\n └── __init__.py\n
Note
A src layout is particularly valuable when developing libraries. It ensures that the library is isolated from any python invocations in the project root and that distributed library code is well separated from the rest of the project source.
A build system is defined, so the project will be installed into the environment:
pyproject.toml[project]\nname = \"example-lib\"\nversion = \"0.1.0\"\ndescription = \"Add your description here\"\nreadme = \"README.md\"\nrequires-python = \">=3.11\"\ndependencies = []\n\n[build-system]\nrequires = [\"uv_build>=0.9.8,<0.10.0\"]\nbuild-backend = \"uv_build\"\n
Tip
You can select a different build backend template by using --build-backend with hatchling, uv_build, flit-core, pdm-backend, setuptools, maturin, or scikit-build-core. An alternative backend is required if you want to create a library with extension modules.
The created module defines a simple API function:
__init__.pydef hello() -> str:\n return \"Hello from example-lib!\"\n
And you can import and execute it using uv run:
$ cd example-lib\n$ uv run python -c \"import example_lib; print(example_lib.hello())\"\nHello from example-lib!\n
","path":["Concepts","Projects","Creating projects"],"tags":[]},{"location":"concepts/projects/init/#projects-with-extension-modules","level":2,"title":"Projects with extension modules","text":"Most Python projects are \"pure Python\", meaning they do not define modules in other languages like C, C++, FORTRAN, or Rust. However, projects with extension modules are often used for performance sensitive code.
Creating a project with an extension module requires choosing an alternative build system. uv supports creating projects with the following build systems that support building extension modules:
maturin for projects with Rustscikit-build-core for projects with C, C++, FORTRAN, Cython
Specify the build system with the --build-backend flag:
$ uv init --build-backend maturin example-ext\n
Note
Using --build-backend implies --package.
The project contains a Cargo.toml and a lib.rs file in addition to the typical Python project files:
$ tree example-ext\nexample-ext\n├── .python-version\n├── Cargo.toml\n├── README.md\n├── pyproject.toml\n└── src\n ├── lib.rs\n └── example_ext\n ├── __init__.py\n └── _core.pyi\n
Note
If using scikit-build-core, you'll see CMake configuration and a main.cpp file instead.
The Rust library defines a simple function:
src/lib.rsuse pyo3::prelude::*;\n\n#[pymodule]\nmod _core {\n use pyo3::prelude::*;\n\n #[pyfunction]\n fn hello_from_bin() -> String {\n \"Hello from example-ext!\".to_string()\n }\n}\n
And the Python module imports it:
src/example_ext/__init__.pyfrom example_ext._core import hello_from_bin\n\n\ndef main() -> None:\n print(hello_from_bin())\n
The command can be executed with uv run:
$ cd example-ext\n$ uv run example-ext\nHello from example-ext!\n
Important
When creating a project with maturin or scikit-build-core, uv configures tool.uv.cache-keys to include common source file types. To force a rebuild, e.g. when changing files outside cache-keys or when not using cache-keys, use --reinstall.
","path":["Concepts","Projects","Creating projects"],"tags":[]},{"location":"concepts/projects/init/#creating-a-minimal-project","level":2,"title":"Creating a minimal project","text":"If you only want to create a pyproject.toml, use the --bare option:
$ uv init example --bare\n
uv will skip creating a Python version pin file, a README, and any source directories or files. Additionally, uv will not initialize a version control system (i.e., git).
$ tree example-bare\nexample-bare\n└── pyproject.toml\n
uv will also not add extra metadata to the pyproject.toml, such as the description or authors.
[project]\nname = \"example\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12\"\ndependencies = []\n
The --bare option can be used with other options like --lib or --build-backend — in these cases uv will still configure a build system but will not create the expected file structure.
When --bare is used, additional features can still be used opt-in:
$ uv init example --bare --description \"Hello world\" --author-from git --vcs git --python-pin\n
","path":["Concepts","Projects","Creating projects"],"tags":[]},{"location":"concepts/projects/layout/","level":1,"title":"Project structure and files","text":"","path":["Concepts","Projects","Project structure and files"],"tags":[]},{"location":"concepts/projects/layout/#the-pyprojecttoml","level":2,"title":"The pyproject.toml","text":"Python project metadata is defined in a pyproject.toml file. uv requires this file to identify the root directory of a project.
Tip
uv init can be used to create a new project. See Creating projects for details.
A minimal project definition includes a name and version:
pyproject.toml[project]\nname = \"example\"\nversion = \"0.1.0\"\n
Additional project metadata and configuration includes:
- Python version requirement
- Dependencies
- Build system
- Entry points (commands)
","path":["Concepts","Projects","Project structure and files"],"tags":[]},{"location":"concepts/projects/layout/#the-project-environment","level":2,"title":"The project environment","text":"When working on a project with uv, uv will create a virtual environment as needed. While some uv commands will create a temporary environment (e.g., uv run --isolated), uv also manages a persistent environment with the project and its dependencies in a .venv directory next to the pyproject.toml. It is stored inside the project to make it easy for editors to find — they need the environment to give code completions and type hints. It is not recommended to include the .venv directory in version control; it is automatically excluded from git with an internal .gitignore file.
To run a command in the project environment, use uv run. Alternatively the project environment can be activated as normal for a virtual environment.
When uv run is invoked, it will create the project environment if it does not exist yet or ensure it is up-to-date if it exists. The project environment can also be explicitly created with uv sync. See the locking and syncing documentation for details.
It is not recommended to modify the project environment manually, e.g., with uv pip install. For project dependencies, use uv add to add a package to the environment. For one-off requirements, use uvx or uv run --with.
Tip
If you don't want uv to manage the project environment, set managed = false to disable automatic locking and syncing of the project. For example:
pyproject.toml[tool.uv]\nmanaged = false\n
","path":["Concepts","Projects","Project structure and files"],"tags":[]},{"location":"concepts/projects/layout/#the-lockfile","level":2,"title":"The lockfile","text":"uv creates a uv.lock file next to the pyproject.toml.
uv.lock is a universal or cross-platform lockfile that captures the packages that would be installed across all possible Python markers such as operating system, architecture, and Python version.
Unlike the pyproject.toml, which is used to specify the broad requirements of your project, the lockfile contains the exact resolved versions that are installed in the project environment. This file should be checked into version control, allowing for consistent and reproducible installations across machines.
A lockfile ensures that developers working on the project are using a consistent set of package versions. Additionally, it ensures when deploying the project as an application that the exact set of used package versions is known.
The lockfile is automatically created and updated during uv invocations that use the project environment, i.e., uv sync and uv run. The lockfile may also be explicitly updated using uv lock.
uv.lock is a human-readable TOML file but is managed by uv and should not be edited manually. The uv.lock format is specific to uv and not usable by other tools.
","path":["Concepts","Projects","Project structure and files"],"tags":[]},{"location":"concepts/projects/layout/#relationship-to-pylocktoml","level":3,"title":"Relationship to pylock.toml","text":"In PEP 751, Python standardized a new resolution file format, pylock.toml.
pylock.toml is a resolution output format intended to replace requirements.txt (e.g., in the context of uv pip compile, whereby a \"locked\" requirements.txt file is generated from a set of input requirements). pylock.toml is standardized and tool-agnostic, such that in the future, pylock.toml files generated by uv could be installed by other tools, and vice versa.
Some of uv's functionality cannot be expressed in the pylock.toml format; as such, uv will continue to use the uv.lock format within the project interface.
However, uv supports pylock.toml as an export target and in the uv pip CLI. For example:
- To export a
uv.lock to the pylock.toml format, run: uv export -o pylock.toml - To generate a
pylock.toml file from a set of requirements, run: uv pip compile requirements.in -o pylock.toml - To install from a
pylock.toml file, run: uv pip sync pylock.toml or uv pip install -r pylock.toml
","path":["Concepts","Projects","Project structure and files"],"tags":[]},{"location":"concepts/projects/run/","level":1,"title":"Running commands in projects","text":"When working on a project, it is installed into the virtual environment at .venv. This environment is isolated from the current shell by default, so invocations that require the project, e.g., python -c \"import example\", will fail. Instead, use uv run to run commands in the project environment:
$ uv run python -c \"import example\"\n
When using run, uv will ensure that the project environment is up-to-date before running the given command.
The given command can be provided by the project environment or exist outside of it, e.g.:
$ # Presuming the project provides `example-cli`\n$ uv run example-cli foo\n\n$ # Running a `bash` script that requires the project to be available\n$ uv run bash scripts/foo.sh\n
","path":["Concepts","Projects","Running commands in projects"],"tags":[]},{"location":"concepts/projects/run/#requesting-additional-dependencies","level":2,"title":"Requesting additional dependencies","text":"Additional dependencies or different versions of dependencies can be requested per invocation.
The --with option is used to include a dependency for the invocation, e.g., to request a different version of httpx:
$ uv run --with httpx==0.26.0 python -c \"import httpx; print(httpx.__version__)\"\n0.26.0\n$ uv run --with httpx==0.25.0 python -c \"import httpx; print(httpx.__version__)\"\n0.25.0\n
The requested version will be respected regardless of the project's requirements. For example, even if the project requires httpx==0.24.0, the output above would be the same.
","path":["Concepts","Projects","Running commands in projects"],"tags":[]},{"location":"concepts/projects/run/#running-scripts","level":2,"title":"Running scripts","text":"Scripts that declare inline metadata are automatically executed in environments isolated from the project. See the scripts guide for more details.
For example, given a script:
example.py# /// script\n# dependencies = [\n# \"httpx\",\n# ]\n# ///\n\nimport httpx\n\nresp = httpx.get(\"https://peps.python.org/api/peps.json\")\ndata = resp.json()\nprint([(k, v[\"title\"]) for k, v in data.items()][:10])\n
The invocation uv run example.py would run isolated from the project with only the given dependencies listed.
","path":["Concepts","Projects","Running commands in projects"],"tags":[]},{"location":"concepts/projects/run/#legacy-scripts-on-windows","level":2,"title":"Legacy scripts on Windows","text":"Support is provided for legacy setuptools scripts. These types of scripts are additional files installed by setuptools in .venv\\Scripts.
Currently only legacy scripts with the .ps1, .cmd, and .bat extensions are supported.
For example, below is an example running a Command Prompt script.
$ uv run --with nuitka==2.6.7 -- nuitka.cmd --version\n
In addition, you don't need to specify the extension. uv will automatically look for files ending in .ps1, .cmd, and .bat in that order of execution on your behalf.
$ uv run --with nuitka==2.6.7 -- nuitka --version\n
","path":["Concepts","Projects","Running commands in projects"],"tags":[]},{"location":"concepts/projects/run/#signal-handling","level":2,"title":"Signal handling","text":"uv does not cede control of the process to the spawned command in order to provide better error messages on failure. Consequently, uv is responsible for forwarding some signals to the child process the requested command runs in.
On Unix systems, uv will forward most signals (with the exception of SIGKILL, SIGCHLD, SIGIO, and SIGPOLL) to the child process. Since terminals send SIGINT to the foreground process group on Ctrl-C, uv will only forward a SIGINT to the child process if it is sent more than once or the child process group differs from uv's.
On Windows, these concepts do not apply and uv ignores Ctrl-C events, deferring handling to the child process so it can exit cleanly.
","path":["Concepts","Projects","Running commands in projects"],"tags":[]},{"location":"concepts/projects/sync/","level":1,"title":"Locking and syncing","text":"Locking is the process of resolving your project's dependencies into a lockfile. Syncing is the process of installing a subset of packages from the lockfile into the project environment.
","path":["Concepts","Projects","Locking and syncing"],"tags":[]},{"location":"concepts/projects/sync/#automatic-lock-and-sync","level":2,"title":"Automatic lock and sync","text":"Locking and syncing are automatic in uv. For example, when uv run is used, the project is locked and synced before invoking the requested command. This ensures the project environment is always up-to-date. Similarly, commands which read the lockfile, such as uv tree, will automatically update it before running.
To disable automatic locking, use the --locked option:
$ uv run --locked ...\n
If the lockfile is not up-to-date, uv will raise an error instead of updating the lockfile.
To use the lockfile without checking if it is up-to-date, use the --frozen option:
$ uv run --frozen ...\n
Similarly, to run a command without checking if the environment is up-to-date, use the --no-sync option:
$ uv run --no-sync ...\n
","path":["Concepts","Projects","Locking and syncing"],"tags":[]},{"location":"concepts/projects/sync/#checking-the-lockfile","level":2,"title":"Checking the lockfile","text":"When considering if the lockfile is up-to-date, uv will check if it matches the project metadata. For example, if you add a dependency to your pyproject.toml, the lockfile will be considered outdated. Similarly, if you change the version constraints for a dependency such that the locked version is excluded, the lockfile will be considered outdated. However, if you change the version constraints such that the existing locked version is still included, the lockfile will still be considered up-to-date.
You can check if the lockfile is up-to-date by passing the --check flag to uv lock:
$ uv lock --check\n
This is equivalent to the --locked flag for other commands.
Important
uv will not consider lockfiles outdated when new versions of packages are released — the lockfile needs to be explicitly updated if you want to upgrade dependencies. See the documentation on upgrading locked package versions for details.
","path":["Concepts","Projects","Locking and syncing"],"tags":[]},{"location":"concepts/projects/sync/#creating-the-lockfile","level":2,"title":"Creating the lockfile","text":"While the lockfile is created automatically, the lockfile may also be explicitly created or updated using uv lock:
$ uv lock\n
","path":["Concepts","Projects","Locking and syncing"],"tags":[]},{"location":"concepts/projects/sync/#syncing-the-environment","level":2,"title":"Syncing the environment","text":"While the environment is synced automatically, it may also be explicitly synced using uv sync:
$ uv sync\n
Syncing the environment manually is especially useful for ensuring your editor has the correct versions of dependencies.
","path":["Concepts","Projects","Locking and syncing"],"tags":[]},{"location":"concepts/projects/sync/#editable-installation","level":3,"title":"Editable installation","text":"When the environment is synced, uv will install the project (and other workspace members) as editable packages, such that re-syncing is not necessary for changes to be reflected in the environment.
To opt-out of this behavior, use the --no-editable option.
Note
If the project does not define a build system, it will not be installed. See the build systems documentation for details.
","path":["Concepts","Projects","Locking and syncing"],"tags":[]},{"location":"concepts/projects/sync/#retaining-extraneous-packages","level":3,"title":"Retaining extraneous packages","text":"Syncing is \"exact\" by default, which means it will remove any packages that are not present in the lockfile.
To retain extraneous packages, use the --inexact option:
$ uv sync --inexact\n
","path":["Concepts","Projects","Locking and syncing"],"tags":[]},{"location":"concepts/projects/sync/#syncing-optional-dependencies","level":3,"title":"Syncing optional dependencies","text":"uv reads optional dependencies from the [project.optional-dependencies] table. These are frequently referred to as \"extras\".
uv does not sync extras by default. Use the --extra option to include an extra.
$ uv sync --extra foo\n
To quickly enable all extras, use the --all-extras option.
See the optional dependencies documentation for details on how to manage optional dependencies.
","path":["Concepts","Projects","Locking and syncing"],"tags":[]},{"location":"concepts/projects/sync/#syncing-development-dependencies","level":3,"title":"Syncing development dependencies","text":"uv reads development dependencies from the [dependency-groups] table (as defined in PEP 735).
The dev group is special-cased and synced by default. See the default groups documentation for details on changing the defaults.
The --no-dev flag can be used to exclude the dev group.
The --only-dev flag can be used to install the dev group without the project and its dependencies.
Additional groups can be included or excluded with the --all-groups, --no-default-groups, --group <name>, --only-group <name>, and --no-group <name> options. The semantics of --only-group are the same as --only-dev, the project will not be included. However, --only-group will also exclude default groups.
Group exclusions always take precedence over inclusions, so given the command:
$ uv sync --no-group foo --group foo\n
The foo group would not be installed.
See the development dependencies documentation for details on how to manage development dependencies.
","path":["Concepts","Projects","Locking and syncing"],"tags":[]},{"location":"concepts/projects/sync/#upgrading-locked-package-versions","level":2,"title":"Upgrading locked package versions","text":"With an existing uv.lock file, uv will prefer the previously locked versions of packages when running uv sync and uv lock. Package versions will only change if the project's dependency constraints exclude the previous, locked version.
To upgrade all packages:
$ uv lock --upgrade\n
To upgrade a single package to the latest version, while retaining the locked versions of all other packages:
$ uv lock --upgrade-package <package>\n
To upgrade a single package to a specific version:
$ uv lock --upgrade-package <package>==<version>\n
In all cases, upgrades are limited to the project's dependency constraints. For example, if the project defines an upper bound for a package then an upgrade will not go beyond that version.
Note
uv applies similar logic to Git dependencies. For example, if a Git dependency references the main branch, uv will prefer the locked commit SHA in an existing uv.lock file over the latest commit on the main branch, unless the --upgrade or --upgrade-package flags are used.
These flags can also be provided to uv sync or uv run to update the lockfile and the environment.
","path":["Concepts","Projects","Locking and syncing"],"tags":[]},{"location":"concepts/projects/sync/#exporting-the-lockfile","level":2,"title":"Exporting the lockfile","text":"If you need to integrate uv with other tools or workflows, you can export uv.lock to the requirements.txt format with uv export --format requirements-txt. The generated requirements.txt file can then be installed via uv pip install, or with other tools like pip.
In general, we recommend against using both a uv.lock and a requirements.txt file. If you find yourself exporting a uv.lock file, consider opening an issue to discuss your use case.
","path":["Concepts","Projects","Locking and syncing"],"tags":[]},{"location":"concepts/projects/sync/#partial-installations","level":2,"title":"Partial installations","text":"Sometimes it's helpful to perform installations in multiple steps, e.g., for optimal layer caching while building a Docker image. uv sync has several flags for this purpose.
--no-install-project: Do not install the current project--no-install-workspace: Do not install any workspace members, including the root project--no-install-package <NO_INSTALL_PACKAGE>: Do not install the given package(s)
When these options are used, all the dependencies of the target are still installed. For example, --no-install-project will omit the project but not any of its dependencies.
If used improperly, these flags can result in a broken environment since a package can be missing its dependencies.
","path":["Concepts","Projects","Locking and syncing"],"tags":[]},{"location":"concepts/projects/workspaces/","level":1,"title":"Using workspaces","text":"Inspired by the Cargo concept of the same name, a workspace is \"a collection of one or more packages, called workspace members, that are managed together.\"
Workspaces organize large codebases by splitting them into multiple packages with common dependencies. Think: a FastAPI-based web application, alongside a series of libraries that are versioned and maintained as separate Python packages, all in the same Git repository.
In a workspace, each package defines its own pyproject.toml, but the workspace shares a single lockfile, ensuring that the workspace operates with a consistent set of dependencies.
As such, uv lock operates on the entire workspace at once, while uv run and uv sync operate on the workspace root by default, though both accept a --package argument, allowing you to run a command in a particular workspace member from any workspace directory.
","path":["Concepts","Projects","Using workspaces"],"tags":[]},{"location":"concepts/projects/workspaces/#getting-started","level":2,"title":"Getting started","text":"To create a workspace, add a tool.uv.workspace table to a pyproject.toml, which will implicitly create a workspace rooted at that package.
Tip
By default, running uv init inside an existing package will add the newly created member to the workspace, creating a tool.uv.workspace table in the workspace root if it doesn't already exist.
In defining a workspace, you must specify the members (required) and exclude (optional) keys, which direct the workspace to include or exclude specific directories as members respectively, and accept lists of globs:
pyproject.toml[project]\nname = \"albatross\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12\"\ndependencies = [\"bird-feeder\", \"tqdm>=4,<5\"]\n\n[tool.uv.sources]\nbird-feeder = { workspace = true }\n\n[tool.uv.workspace]\nmembers = [\"packages/*\"]\nexclude = [\"packages/seeds\"]\n
Every directory included by the members globs (and not excluded by the exclude globs) must contain a pyproject.toml file. However, workspace members can be either applications or libraries; both are supported in the workspace context.
Every workspace needs a root, which is also a workspace member. In the above example, albatross is the workspace root, and the workspace members include all projects under the packages directory, except seeds.
By default, uv run and uv sync operates on the workspace root. For example, in the above example, uv run and uv run --package albatross would be equivalent, while uv run --package bird-feeder would run the command in the bird-feeder package.
","path":["Concepts","Projects","Using workspaces"],"tags":[]},{"location":"concepts/projects/workspaces/#workspace-sources","level":2,"title":"Workspace sources","text":"Within a workspace, dependencies on workspace members are facilitated via tool.uv.sources, as in:
pyproject.toml[project]\nname = \"albatross\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12\"\ndependencies = [\"bird-feeder\", \"tqdm>=4,<5\"]\n\n[tool.uv.sources]\nbird-feeder = { workspace = true }\n\n[tool.uv.workspace]\nmembers = [\"packages/*\"]\n\n[build-system]\nrequires = [\"uv_build>=0.9.8,<0.10.0\"]\nbuild-backend = \"uv_build\"\n
In this example, the albatross project depends on the bird-feeder project, which is a member of the workspace. The workspace = true key-value pair in the tool.uv.sources table indicates the bird-feeder dependency should be provided by the workspace, rather than fetched from PyPI or another registry.
Note
Dependencies between workspace members are editable.
Any tool.uv.sources definitions in the workspace root apply to all members, unless overridden in the tool.uv.sources of a specific member. For example, given the following pyproject.toml:
pyproject.toml[project]\nname = \"albatross\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12\"\ndependencies = [\"bird-feeder\", \"tqdm>=4,<5\"]\n\n[tool.uv.sources]\nbird-feeder = { workspace = true }\ntqdm = { git = \"https://github.com/tqdm/tqdm\" }\n\n[tool.uv.workspace]\nmembers = [\"packages/*\"]\n\n[build-system]\nrequires = [\"uv_build>=0.9.8,<0.10.0\"]\nbuild-backend = \"uv_build\"\n
Every workspace member would, by default, install tqdm from GitHub, unless a specific member overrides the tqdm entry in its own tool.uv.sources table.
Note
If a workspace member provides tool.uv.sources for some dependency, it will ignore any tool.uv.sources for the same dependency in the workspace root, even if the member's source is limited by a marker that doesn't match the current platform.
","path":["Concepts","Projects","Using workspaces"],"tags":[]},{"location":"concepts/projects/workspaces/#workspace-layouts","level":2,"title":"Workspace layouts","text":"The most common workspace layout can be thought of as a root project with a series of accompanying libraries.
For example, continuing with the above example, this workspace has an explicit root at albatross, with two libraries (bird-feeder and seeds) in the packages directory:
albatross\n├── packages\n│ ├── bird-feeder\n│ │ ├── pyproject.toml\n│ │ └── src\n│ │ └── bird_feeder\n│ │ ├── __init__.py\n│ │ └── foo.py\n│ └── seeds\n│ ├── pyproject.toml\n│ └── src\n│ └── seeds\n│ ├── __init__.py\n│ └── bar.py\n├── pyproject.toml\n├── README.md\n├── uv.lock\n└── src\n └── albatross\n └── main.py\n
Since seeds was excluded in the pyproject.toml, the workspace has two members total: albatross (the root) and bird-feeder.
","path":["Concepts","Projects","Using workspaces"],"tags":[]},{"location":"concepts/projects/workspaces/#when-not-to-use-workspaces","level":2,"title":"When (not) to use workspaces","text":"Workspaces are intended to facilitate the development of multiple interconnected packages within a single repository. As a codebase grows in complexity, it can be helpful to split it into smaller, composable packages, each with their own dependencies and version constraints.
Workspaces help enforce isolation and separation of concerns. For example, in uv, we have separate packages for the core library and the command-line interface, enabling us to test the core library independently of the CLI, and vice versa.
Other common use cases for workspaces include:
- A library with a performance-critical subroutine implemented in an extension module (Rust, C++, etc.).
- A library with a plugin system, where each plugin is a separate workspace package with a dependency on the root.
Workspaces are not suited for cases in which members have conflicting requirements, or desire a separate virtual environment for each member. In this case, path dependencies are often preferable. For example, rather than grouping albatross and its members in a workspace, you can always define each package as its own independent project, with inter-package dependencies defined as path dependencies in tool.uv.sources:
pyproject.toml[project]\nname = \"albatross\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12\"\ndependencies = [\"bird-feeder\", \"tqdm>=4,<5\"]\n\n[tool.uv.sources]\nbird-feeder = { path = \"packages/bird-feeder\" }\n\n[build-system]\nrequires = [\"uv_build>=0.9.8,<0.10.0\"]\nbuild-backend = \"uv_build\"\n
This approach conveys many of the same benefits, but allows for more fine-grained control over dependency resolution and virtual environment management (with the downside that uv run --package is no longer available; instead, commands must be run from the relevant package directory).
Finally, uv's workspaces enforce a single requires-python for the entire workspace, taking the intersection of all members' requires-python values. If you need to support testing a given member on a Python version that isn't supported by the rest of the workspace, you may need to use uv pip to install that member in a separate virtual environment.
Note
As Python does not provide dependency isolation, uv can't ensure that a package uses its declared dependencies and nothing else. For workspaces specifically, uv can't ensure that packages don't import dependencies declared by another workspace member.
","path":["Concepts","Projects","Using workspaces"],"tags":[]},{"location":"getting-started/","level":1,"title":"Getting started","text":"To help you get started with uv, we'll cover a few important topics:
- Installing uv
- First steps after installation
- An overview of uv's features
- How to get help
Read on, or jump ahead to another section:
- Get going quickly with guides for common workflows.
- Learn more about the core concepts in uv.
- Use the reference documentation to find details about something specific.
","path":["Getting started"],"tags":[]},{"location":"getting-started/features/","level":1,"title":"Features","text":"uv provides essential features for Python development — from installing Python and hacking on simple scripts to working on large projects that support multiple Python versions and platforms.
uv's interface can be broken down into sections, which are usable independently or together.
","path":["Getting started","Features"],"tags":[]},{"location":"getting-started/features/#python-versions","level":2,"title":"Python versions","text":"Installing and managing Python itself.
uv python install: Install Python versions.uv python list: View available Python versions.uv python find: Find an installed Python version.uv python pin: Pin the current project to use a specific Python version.uv python uninstall: Uninstall a Python version.
See the guide on installing Python to get started.
","path":["Getting started","Features"],"tags":[]},{"location":"getting-started/features/#scripts","level":2,"title":"Scripts","text":"Executing standalone Python scripts, e.g., example.py.
uv run: Run a script.uv add --script: Add a dependency to a script.uv remove --script: Remove a dependency from a script.
See the guide on running scripts to get started.
","path":["Getting started","Features"],"tags":[]},{"location":"getting-started/features/#projects","level":2,"title":"Projects","text":"Creating and working on Python projects, i.e., with a pyproject.toml.
uv init: Create a new Python project.uv add: Add a dependency to the project.uv remove: Remove a dependency from the project.uv sync: Sync the project's dependencies with the environment.uv lock: Create a lockfile for the project's dependencies.uv run: Run a command in the project environment.uv tree: View the dependency tree for the project.uv build: Build the project into distribution archives.uv publish: Publish the project to a package index.
See the guide on projects to get started.
","path":["Getting started","Features"],"tags":[]},{"location":"getting-started/features/#tools","level":2,"title":"Tools","text":"Running and installing tools published to Python package indexes, e.g., ruff or black.
uvx / uv tool run: Run a tool in a temporary environment.uv tool install: Install a tool user-wide.uv tool uninstall: Uninstall a tool.uv tool list: List installed tools.uv tool update-shell: Update the shell to include tool executables.
See the guide on tools to get started.
","path":["Getting started","Features"],"tags":[]},{"location":"getting-started/features/#the-pip-interface","level":2,"title":"The pip interface","text":"Manually managing environments and packages — intended to be used in legacy workflows or cases where the high-level commands do not provide enough control.
Creating virtual environments (replacing venv and virtualenv):
uv venv: Create a new virtual environment.
See the documentation on using environments for details.
Managing packages in an environment (replacing pip and pipdeptree):
uv pip install: Install packages into the current environment.uv pip show: Show details about an installed package.uv pip freeze: List installed packages and their versions.uv pip check: Check that the current environment has compatible packages.uv pip list: List installed packages.uv pip uninstall: Uninstall packages.uv pip tree: View the dependency tree for the environment.
See the documentation on managing packages for details.
Locking packages in an environment (replacing pip-tools):
uv pip compile: Compile requirements into a lockfile.uv pip sync: Sync an environment with a lockfile.
See the documentation on locking environments for details.
Important
These commands do not exactly implement the interfaces and behavior of the tools they are based on. The further you stray from common workflows, the more likely you are to encounter differences. Consult the pip-compatibility guide for details.
","path":["Getting started","Features"],"tags":[]},{"location":"getting-started/features/#utility","level":2,"title":"Utility","text":"Managing and inspecting uv's state, such as the cache, storage directories, or performing a self-update:
uv cache clean: Remove cache entries.uv cache prune: Remove outdated cache entries.uv cache dir: Show the uv cache directory path.uv tool dir: Show the uv tool directory path.uv python dir: Show the uv installed Python versions path.uv self update: Update uv to the latest version.
","path":["Getting started","Features"],"tags":[]},{"location":"getting-started/features/#next-steps","level":2,"title":"Next steps","text":"Read the guides for an introduction to each feature, check out the concept pages for in-depth details about uv's features, or learn how to get help if you run into any problems.
","path":["Getting started","Features"],"tags":[]},{"location":"getting-started/first-steps/","level":1,"title":"First steps with uv","text":"After installing uv, you can check that uv is available by running the uv command:
$ uv\nAn extremely fast Python package manager.\n\nUsage: uv [OPTIONS] <COMMAND>\n\n...\n
You should see a help menu listing the available commands.
","path":["Getting started","First steps with uv"],"tags":[]},{"location":"getting-started/first-steps/#next-steps","level":2,"title":"Next steps","text":"Now that you've confirmed uv is installed, check out an overview of features, learn how to get help if you run into any problems, or jump to the guides to start using uv.
","path":["Getting started","First steps with uv"],"tags":[]},{"location":"getting-started/help/","level":1,"title":"Getting help","text":"","path":["Getting started","Getting help"],"tags":[]},{"location":"getting-started/help/#help-menus","level":2,"title":"Help menus","text":"The --help flag can be used to view the help menu for a command, e.g., for uv:
$ uv --help\n
To view the help menu for a specific command, e.g., for uv init:
$ uv init --help\n
When using the --help flag, uv displays a condensed help menu. To view a longer help menu for a command, use uv help:
$ uv help\n
To view the long help menu for a specific command, e.g., for uv init:
$ uv help init\n
When using the long help menu, uv will attempt to use less or more to \"page\" the output so it is not all displayed at once. To exit the pager, press q.
","path":["Getting started","Getting help"],"tags":[]},{"location":"getting-started/help/#displaying-verbose-output","level":2,"title":"Displaying verbose output","text":"The -v flag can be used to display verbose output for a command, e.g., for uv sync:
$ uv sync -v\n
The -v flag can be repeated to increase verbosity, e.g.:
$ uv sync -vv\n
Often, the verbose output will include additional information about why uv is behaving in a certain way.
","path":["Getting started","Getting help"],"tags":[]},{"location":"getting-started/help/#viewing-the-version","level":2,"title":"Viewing the version","text":"When seeking help, it's important to determine the version of uv that you're using — sometimes the problem is already solved in a newer version.
To check the installed version:
$ uv self version\n
The following are also valid:
$ uv --version # Same output as `uv self version`\n$ uv -V # Will not include the build commit and date\n
Note
Before uv 0.7.0, uv version was used instead of uv self version.
","path":["Getting started","Getting help"],"tags":[]},{"location":"getting-started/help/#troubleshooting-issues","level":2,"title":"Troubleshooting issues","text":"The reference documentation contains a troubleshooting guide for common issues.
","path":["Getting started","Getting help"],"tags":[]},{"location":"getting-started/help/#open-an-issue-on-github","level":2,"title":"Open an issue on GitHub","text":"The issue tracker on GitHub is a good place to report bugs and request features. Make sure to search for similar issues first, as it is common for someone else to encounter the same problem.
","path":["Getting started","Getting help"],"tags":[]},{"location":"getting-started/help/#chat-on-discord","level":2,"title":"Chat on Discord","text":"Astral has a Discord server, which is a great place to ask questions, learn more about uv, and engage with other community members.
","path":["Getting started","Getting help"],"tags":[]},{"location":"getting-started/installation/","level":1,"title":"Installing uv","text":"","path":["Getting started","Installing uv"],"tags":[]},{"location":"getting-started/installation/#installation-methods","level":2,"title":"Installation methods","text":"Install uv with our standalone installers or your package manager of choice.
","path":["Getting started","Installing uv"],"tags":[]},{"location":"getting-started/installation/#standalone-installer","level":3,"title":"Standalone installer","text":"uv provides a standalone installer to download and install uv:
macOS and LinuxWindows Use curl to download the script and execute it with sh:
$ curl -LsSf https://astral.sh/uv/install.sh | sh\n
If your system doesn't have curl, you can use wget:
$ wget -qO- https://astral.sh/uv/install.sh | sh\n
Request a specific version by including it in the URL:
$ curl -LsSf https://astral.sh/uv/0.9.8/install.sh | sh\n
Use irm to download the script and execute it with iex:
PS> powershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n
Changing the execution policy allows running a script from the internet.
Request a specific version by including it in the URL:
PS> powershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/0.9.8/install.ps1 | iex\"\n
Tip
The installation script may be inspected before use:
macOS and LinuxWindows $ curl -LsSf https://astral.sh/uv/install.sh | less\n
PS> powershell -c \"irm https://astral.sh/uv/install.ps1 | more\"\n
Alternatively, the installer or binaries can be downloaded directly from GitHub.
See the reference documentation on the installer for details on customizing your uv installation.
","path":["Getting started","Installing uv"],"tags":[]},{"location":"getting-started/installation/#pypi","level":3,"title":"PyPI","text":"For convenience, uv is published to PyPI.
If installing from PyPI, we recommend installing uv into an isolated environment, e.g., with pipx:
$ pipx install uv\n
However, pip can also be used:
$ pip install uv\n
Note
uv ships with prebuilt distributions (wheels) for many platforms; if a wheel is not available for a given platform, uv will be built from source, which requires a Rust toolchain. See the contributing setup guide for details on building uv from source.
","path":["Getting started","Installing uv"],"tags":[]},{"location":"getting-started/installation/#homebrew","level":3,"title":"Homebrew","text":"uv is available in the core Homebrew packages.
$ brew install uv\n
","path":["Getting started","Installing uv"],"tags":[]},{"location":"getting-started/installation/#macports","level":3,"title":"MacPorts","text":"uv is available via MacPorts.
$ sudo port install uv\n
","path":["Getting started","Installing uv"],"tags":[]},{"location":"getting-started/installation/#winget","level":3,"title":"WinGet","text":"uv is available via WinGet.
$ winget install --id=astral-sh.uv -e\n
","path":["Getting started","Installing uv"],"tags":[]},{"location":"getting-started/installation/#scoop","level":3,"title":"Scoop","text":"uv is available via Scoop.
$ scoop install main/uv\n
","path":["Getting started","Installing uv"],"tags":[]},{"location":"getting-started/installation/#docker","level":3,"title":"Docker","text":"uv provides a Docker image at ghcr.io/astral-sh/uv.
See our guide on using uv in Docker for more details.
","path":["Getting started","Installing uv"],"tags":[]},{"location":"getting-started/installation/#github-releases","level":3,"title":"GitHub Releases","text":"uv release artifacts can be downloaded directly from GitHub Releases.
Each release page includes binaries for all supported platforms as well as instructions for using the standalone installer via github.com instead of astral.sh.
","path":["Getting started","Installing uv"],"tags":[]},{"location":"getting-started/installation/#cargo","level":3,"title":"Cargo","text":"uv is available via Cargo, but must be built from Git rather than crates.io due to its dependency on unpublished crates.
$ cargo install --git https://github.com/astral-sh/uv uv\n
Note
This method builds uv from source, which requires a compatible Rust toolchain.
","path":["Getting started","Installing uv"],"tags":[]},{"location":"getting-started/installation/#upgrading-uv","level":2,"title":"Upgrading uv","text":"When uv is installed via the standalone installer, it can update itself on-demand:
$ uv self update\n
Tip
Updating uv will re-run the installer and can modify your shell profiles. To disable this behavior, set UV_NO_MODIFY_PATH=1.
When another installation method is used, self-updates are disabled. Use the package manager's upgrade method instead. For example, with pip:
$ pip install --upgrade uv\n
","path":["Getting started","Installing uv"],"tags":[]},{"location":"getting-started/installation/#shell-autocompletion","level":2,"title":"Shell autocompletion","text":"Tip
You can run echo $SHELL to help you determine your shell.
To enable shell autocompletion for uv commands, run one of the following:
BashZshfishElvishPowerShell / pwsh echo 'eval \"$(uv generate-shell-completion bash)\"' >> ~/.bashrc\n
echo 'eval \"$(uv generate-shell-completion zsh)\"' >> ~/.zshrc\n
echo 'uv generate-shell-completion fish | source' > ~/.config/fish/completions/uv.fish\n
echo 'eval (uv generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv\n
if (!(Test-Path -Path $PROFILE)) {\n New-Item -ItemType File -Path $PROFILE -Force\n}\nAdd-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'\n
To enable shell autocompletion for uvx, run one of the following:
BashZshfishElvishPowerShell / pwsh echo 'eval \"$(uvx --generate-shell-completion bash)\"' >> ~/.bashrc\n
echo 'eval \"$(uvx --generate-shell-completion zsh)\"' >> ~/.zshrc\n
echo 'uvx --generate-shell-completion fish | source' > ~/.config/fish/completions/uvx.fish\n
echo 'eval (uvx --generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv\n
if (!(Test-Path -Path $PROFILE)) {\n New-Item -ItemType File -Path $PROFILE -Force\n}\nAdd-Content -Path $PROFILE -Value '(& uvx --generate-shell-completion powershell) | Out-String | Invoke-Expression'\n
Then restart the shell or source the shell config file.
","path":["Getting started","Installing uv"],"tags":[]},{"location":"getting-started/installation/#uninstallation","level":2,"title":"Uninstallation","text":"If you need to remove uv from your system, follow these steps:
-
Clean up stored data (optional):
$ uv cache clean\n$ rm -r \"$(uv python dir)\"\n$ rm -r \"$(uv tool dir)\"\n
Tip
Before removing the binaries, you may want to remove any data that uv has stored.
-
Remove the uv, uvx, and uvw binaries:
macOS and LinuxWindows $ rm ~/.local/bin/uv ~/.local/bin/uvx\n
PS> rm $HOME\\.local\\bin\\uv.exe\nPS> rm $HOME\\.local\\bin\\uvx.exe\nPS> rm $HOME\\.local\\bin\\uvw.exe\n
Note
Prior to 0.5.0, uv was installed into ~/.cargo/bin. The binaries can be removed from there to uninstall. Upgrading from an older version will not automatically remove the binaries from ~/.cargo/bin.
","path":["Getting started","Installing uv"],"tags":[]},{"location":"getting-started/installation/#next-steps","level":2,"title":"Next steps","text":"See the first steps or jump straight to the guides to start using uv.
","path":["Getting started","Installing uv"],"tags":[]},{"location":"guides/","level":1,"title":"Guides overview","text":"Check out one of the core guides to get started:
- Installing Python versions
- Running scripts and declaring dependencies
- Running and installing applications as tools
- Creating and working on projects
- Building and publishing packages
- Integrate uv with other software, e.g., Docker, GitHub, PyTorch, and more
Or, explore the concept documentation for comprehensive breakdown of each feature.
","path":["Guides","Guides overview"],"tags":[]},{"location":"guides/install-python/","level":1,"title":"Installing Python","text":"If Python is already installed on your system, uv will detect and use it without configuration. However, uv can also install and manage Python versions. uv automatically installs missing Python versions as needed — you don't need to install Python to get started.
","path":["Guides","Installing and managing Python"],"tags":[]},{"location":"guides/install-python/#getting-started","level":2,"title":"Getting started","text":"To install the latest Python version:
$ uv python install\n
Note
Python does not publish official distributable binaries. As such, uv uses distributions from the Astral python-build-standalone project. See the Python distributions documentation for more details.
Once Python is installed, it will be used by uv commands automatically. uv also adds the installed version to your PATH:
$ python3.13\n
uv only installs a versioned executable by default. To install python and python3 executables, include the experimental --default option:
$ uv python install --default\n
Tip
See the documentation on installing Python executables for more details.
","path":["Guides","Installing and managing Python"],"tags":[]},{"location":"guides/install-python/#installing-a-specific-version","level":2,"title":"Installing a specific version","text":"To install a specific Python version:
$ uv python install 3.12\n
To install multiple Python versions:
$ uv python install 3.11 3.12\n
To install an alternative Python implementation, e.g., PyPy:
$ uv python install pypy@3.10\n
See the python install documentation for more details.
","path":["Guides","Installing and managing Python"],"tags":[]},{"location":"guides/install-python/#reinstalling-python","level":2,"title":"Reinstalling Python","text":"To reinstall uv-managed Python versions, use --reinstall, e.g.:
$ uv python install --reinstall\n
This will reinstall all previously installed Python versions. Improvements are constantly being added to the Python distributions, so reinstalling may resolve bugs even if the Python version does not change.
","path":["Guides","Installing and managing Python"],"tags":[]},{"location":"guides/install-python/#viewing-python-installations","level":2,"title":"Viewing Python installations","text":"To view available and installed Python versions:
$ uv python list\n
See the python list documentation for more details.
","path":["Guides","Installing and managing Python"],"tags":[]},{"location":"guides/install-python/#automatic-python-downloads","level":2,"title":"Automatic Python downloads","text":"Python does not need to be explicitly installed to use uv. By default, uv will automatically download Python versions when they are required. For example, the following would download Python 3.12 if it was not installed:
$ uvx python@3.12 -c \"print('hello world')\"\n
Even if a specific Python version is not requested, uv will download the latest version on demand. For example, if there are no Python versions on your system, the following will install Python before creating a new virtual environment:
$ uv venv\n
Tip
Automatic Python downloads can be easily disabled if you want more control over when Python is downloaded.
","path":["Guides","Installing and managing Python"],"tags":[]},{"location":"guides/install-python/#using-existing-python-versions","level":2,"title":"Using existing Python versions","text":"uv will use existing Python installations if present on your system. There is no configuration necessary for this behavior: uv will use the system Python if it satisfies the requirements of the command invocation. See the Python discovery documentation for details.
To force uv to use the system Python, provide the --no-managed-python flag. See the Python version preference documentation for more details.
","path":["Guides","Installing and managing Python"],"tags":[]},{"location":"guides/install-python/#upgrading-python-versions","level":2,"title":"Upgrading Python versions","text":"Important
Support for upgrading Python patch versions is in preview. This means the behavior is experimental and subject to change.
To upgrade a Python version to the latest supported patch release:
$ uv python upgrade 3.12\n
To upgrade all uv-managed Python versions:
$ uv python upgrade\n
See the python upgrade documentation for more details.
","path":["Guides","Installing and managing Python"],"tags":[]},{"location":"guides/install-python/#next-steps","level":2,"title":"Next steps","text":"To learn more about uv python, see the Python version concept page and the command reference.
Or, read on to learn how to run scripts and invoke Python with uv.
","path":["Guides","Installing and managing Python"],"tags":[]},{"location":"guides/package/","level":1,"title":"Building and publishing a package","text":"uv supports building Python packages into source and binary distributions via uv build and uploading them to a registry with uv publish.
","path":["Guides","Building and publishing a package"],"tags":[]},{"location":"guides/package/#preparing-your-project-for-packaging","level":2,"title":"Preparing your project for packaging","text":"Before attempting to publish your project, you'll want to make sure it's ready to be packaged for distribution.
If your project does not include a [build-system] definition in the pyproject.toml, uv will not build it by default. This means that your project may not be ready for distribution. Read more about the effect of declaring a build system in the project concept documentation.
Note
If you have internal packages that you do not want to be published, you can mark them as private:
[project]\nclassifiers = [\"Private :: Do Not Upload\"]\n
This setting makes PyPI reject your uploaded package from publishing. It does not affect security or privacy settings on alternative registries.
We also recommend only generating per-project PyPI API tokens: Without a PyPI token matching the project, it can't be accidentally published.
","path":["Guides","Building and publishing a package"],"tags":[]},{"location":"guides/package/#building-your-package","level":2,"title":"Building your package","text":"Build your package with uv build:
$ uv build\n
By default, uv build will build the project in the current directory, and place the built artifacts in a dist/ subdirectory.
Alternatively, uv build <SRC> will build the package in the specified directory, while uv build --package <PACKAGE> will build the specified package within the current workspace.
Info
By default, uv build respects tool.uv.sources when resolving build dependencies from the build-system.requires section of the pyproject.toml. When publishing a package, we recommend running uv build --no-sources to ensure that the package builds correctly when tool.uv.sources is disabled, as is the case when using other build tools, like pypa/build.
","path":["Guides","Building and publishing a package"],"tags":[]},{"location":"guides/package/#updating-your-version","level":2,"title":"Updating your version","text":"The uv version command provides conveniences for updating the version of your package before you publish it. See the project docs for reading your package's version.
To update to an exact version, provide it as a positional argument:
$ uv version 1.0.0\nhello-world 0.7.0 => 1.0.0\n
To preview the change without updating the pyproject.toml, use the --dry-run flag:
$ uv version 2.0.0 --dry-run\nhello-world 1.0.0 => 2.0.0\n$ uv version\nhello-world 1.0.0\n
To increase the version of your package semantics, use the --bump option:
$ uv version --bump minor\nhello-world 1.2.3 => 1.3.0\n
The --bump option supports the following common version components: major, minor, patch, stable, alpha, beta, rc, post, and dev. When provided more than once, the components will be applied in order, from largest (major) to smallest (dev).
To move from a stable to pre-release version, bump one of the major, minor, or patch components in addition to the pre-release component:
$ uv version --bump patch --bump beta\nhello-world 1.3.0 => 1.3.1b1\n$ uv version --bump major --bump alpha\nhello-world 1.3.0 => 2.0.0a1\n
When moving from a pre-release to a new pre-release version, just bump the relevant pre-release component:
$ uv version --bump beta\nhello-world 1.3.0b1 => 1.3.0b2\n
When moving from a pre-release to a stable version, the stable option can be used to clear the pre-release component:
$ uv version --bump stable\nhello-world 1.3.1b2 => 1.3.1\n
Info
By default, when uv version modifies the project it will perform a lock and sync. To prevent locking and syncing, use --frozen, or, to just prevent syncing, use --no-sync.
","path":["Guides","Building and publishing a package"],"tags":[]},{"location":"guides/package/#publishing-your-package","level":2,"title":"Publishing your package","text":"Note
A complete guide to publishing from GitHub Actions to PyPI can be found in the GitHub Guide
Publish your package with uv publish:
$ uv publish\n
Set a PyPI token with --token or UV_PUBLISH_TOKEN, or set a username with --username or UV_PUBLISH_USERNAME and password with --password or UV_PUBLISH_PASSWORD. For publishing to PyPI from GitHub Actions or another Trusted Publisher, you don't need to set any credentials. Instead, add a trusted publisher to the PyPI project.
Note
PyPI does not support publishing with username and password anymore, instead you need to generate a token. Using a token is equivalent to setting --username __token__ and using the token as password.
If you're using a custom index through [[tool.uv.index]], add publish-url and use uv publish --index <name>. For example:
[[tool.uv.index]]\nname = \"testpypi\"\nurl = \"https://test.pypi.org/simple/\"\npublish-url = \"https://test.pypi.org/legacy/\"\nexplicit = true\n
Note
When using uv publish --index <name>, the pyproject.toml must be present, i.e., you need to have a checkout step in a publish CI job.
Even though uv publish retries failed uploads, it can happen that publishing fails in the middle, with some files uploaded and some files still missing. With PyPI, you can retry the exact same command, existing identical files will be ignored. With other registries, use --check-url <index url> with the index URL (not the publishing URL) the packages belong to. When using --index, the index URL is used as check URL. uv will skip uploading files that are identical to files in the registry, and it will also handle raced parallel uploads. Note that existing files need to match exactly with those previously uploaded to the registry, this avoids accidentally publishing source distribution and wheels with different contents for the same version.
","path":["Guides","Building and publishing a package"],"tags":[]},{"location":"guides/package/#installing-your-package","level":2,"title":"Installing your package","text":"Test that the package can be installed and imported with uv run:
$ uv run --with <PACKAGE> --no-project -- python -c \"import <PACKAGE>\"\n
The --no-project flag is used to avoid installing the package from your local project directory.
Tip
If you have recently installed the package, you may need to include the --refresh-package <PACKAGE> option to avoid using a cached version of the package.
","path":["Guides","Building and publishing a package"],"tags":[]},{"location":"guides/package/#next-steps","level":2,"title":"Next steps","text":"To learn more about publishing packages, check out the PyPA guides on building and publishing.
Or, read on for guides on integrating uv with other software.
","path":["Guides","Building and publishing a package"],"tags":[]},{"location":"guides/projects/","level":1,"title":"Working on projects","text":"uv supports managing Python projects, which define their dependencies in a pyproject.toml file.
","path":["Guides","Working on projects"],"tags":[]},{"location":"guides/projects/#creating-a-new-project","level":2,"title":"Creating a new project","text":"You can create a new Python project using the uv init command:
$ uv init hello-world\n$ cd hello-world\n
Alternatively, you can initialize a project in the working directory:
$ mkdir hello-world\n$ cd hello-world\n$ uv init\n
uv will create the following files:
├── .gitignore\n├── .python-version\n├── README.md\n├── main.py\n└── pyproject.toml\n
The main.py file contains a simple \"Hello world\" program. Try it out with uv run:
$ uv run main.py\nHello from hello-world!\n
","path":["Guides","Working on projects"],"tags":[]},{"location":"guides/projects/#project-structure","level":2,"title":"Project structure","text":"A project consists of a few important parts that work together and allow uv to manage your project. In addition to the files created by uv init, uv will create a virtual environment and uv.lock file in the root of your project the first time you run a project command, i.e., uv run, uv sync, or uv lock.
A complete listing would look like:
.\n├── .venv\n│ ├── bin\n│ ├── lib\n│ └── pyvenv.cfg\n├── .python-version\n├── README.md\n├── main.py\n├── pyproject.toml\n└── uv.lock\n
","path":["Guides","Working on projects"],"tags":[]},{"location":"guides/projects/#pyprojecttoml","level":3,"title":"pyproject.toml","text":"The pyproject.toml contains metadata about your project:
pyproject.toml[project]\nname = \"hello-world\"\nversion = \"0.1.0\"\ndescription = \"Add your description here\"\nreadme = \"README.md\"\ndependencies = []\n
You'll use this file to specify dependencies, as well as details about the project such as its description or license. You can edit this file manually, or use commands like uv add and uv remove to manage your project from the terminal.
Tip
See the official pyproject.toml guide for more details on getting started with the pyproject.toml format.
You'll also use this file to specify uv configuration options in a [tool.uv] section.
","path":["Guides","Working on projects"],"tags":[]},{"location":"guides/projects/#python-version","level":3,"title":".python-version","text":"The .python-version file contains the project's default Python version. This file tells uv which Python version to use when creating the project's virtual environment.
","path":["Guides","Working on projects"],"tags":[]},{"location":"guides/projects/#venv","level":3,"title":".venv","text":"The .venv folder contains your project's virtual environment, a Python environment that is isolated from the rest of your system. This is where uv will install your project's dependencies.
See the project environment documentation for more details.
","path":["Guides","Working on projects"],"tags":[]},{"location":"guides/projects/#uvlock","level":3,"title":"uv.lock","text":"uv.lock is a cross-platform lockfile that contains exact information about your project's dependencies. Unlike the pyproject.toml which is used to specify the broad requirements of your project, the lockfile contains the exact resolved versions that are installed in the project environment. This file should be checked into version control, allowing for consistent and reproducible installations across machines.
uv.lock is a human-readable TOML file but is managed by uv and should not be edited manually.
See the lockfile documentation for more details.
","path":["Guides","Working on projects"],"tags":[]},{"location":"guides/projects/#managing-dependencies","level":2,"title":"Managing dependencies","text":"You can add dependencies to your pyproject.toml with the uv add command. This will also update the lockfile and project environment:
$ uv add requests\n
You can also specify version constraints or alternative sources:
$ # Specify a version constraint\n$ uv add 'requests==2.31.0'\n\n$ # Add a git dependency\n$ uv add git+https://github.com/psf/requests\n
If you're migrating from a requirements.txt file, you can use uv add with the -r flag to add all dependencies from the file:
$ # Add all dependencies from `requirements.txt`.\n$ uv add -r requirements.txt -c constraints.txt\n
To remove a package, you can use uv remove:
$ uv remove requests\n
To upgrade a package, run uv lock with the --upgrade-package flag:
$ uv lock --upgrade-package requests\n
The --upgrade-package flag will attempt to update the specified package to the latest compatible version, while keeping the rest of the lockfile intact.
See the documentation on managing dependencies for more details.
","path":["Guides","Working on projects"],"tags":[]},{"location":"guides/projects/#viewing-your-version","level":2,"title":"Viewing your version","text":"The uv version command can be used to read your package's version.
To get the version of your package, run uv version:
$ uv version\nhello-world 0.7.0\n
To get the version without the package name, use the --short option:
$ uv version --short\n0.7.0\n
To get version information in a JSON format, use the --output-format json option:
$ uv version --output-format json\n{\n \"package_name\": \"hello-world\",\n \"version\": \"0.7.0\",\n \"commit_info\": null\n}\n
See the publishing guide for details on updating your package version.
","path":["Guides","Working on projects"],"tags":[]},{"location":"guides/projects/#running-commands","level":2,"title":"Running commands","text":"uv run can be used to run arbitrary scripts or commands in your project environment.
Prior to every uv run invocation, uv will verify that the lockfile is up-to-date with the pyproject.toml, and that the environment is up-to-date with the lockfile, keeping your project in-sync without the need for manual intervention. uv run guarantees that your command is run in a consistent, locked environment.
For example, to use flask:
$ uv add flask\n$ uv run -- flask run -p 3000\n
Or, to run a script:
example.py# Require a project dependency\nimport flask\n\nprint(\"hello world\")\n
$ uv run example.py\n
Alternatively, you can use uv sync to manually update the environment then activate it before executing a command:
macOS and LinuxWindows $ uv sync\n$ source .venv/bin/activate\n$ flask run -p 3000\n$ python example.py\n
PS> uv sync\nPS> .venv\\Scripts\\activate\nPS> flask run -p 3000\nPS> python example.py\n
Note
The virtual environment must be active to run scripts and commands in the project without uv run. Virtual environment activation differs per shell and platform.
See the documentation on running commands and scripts in projects for more details.
","path":["Guides","Working on projects"],"tags":[]},{"location":"guides/projects/#building-distributions","level":2,"title":"Building distributions","text":"uv build can be used to build source distributions and binary distributions (wheel) for your project.
By default, uv build will build the project in the current directory, and place the built artifacts in a dist/ subdirectory:
$ uv build\n$ ls dist/\nhello-world-0.1.0-py3-none-any.whl\nhello-world-0.1.0.tar.gz\n
See the documentation on building projects for more details.
","path":["Guides","Working on projects"],"tags":[]},{"location":"guides/projects/#next-steps","level":2,"title":"Next steps","text":"To learn more about working on projects with uv, see the projects concept page and the command reference.
Or, read on to learn how to build and publish your project to a package index.
","path":["Guides","Working on projects"],"tags":[]},{"location":"guides/scripts/","level":1,"title":"Running scripts","text":"A Python script is a file intended for standalone execution, e.g., with python <script>.py. Using uv to execute scripts ensures that script dependencies are managed without manually managing environments.
Note
If you are not familiar with Python environments: every Python installation has an environment that packages can be installed in. Typically, creating virtual environments is recommended to isolate packages required by each script. uv automatically manages virtual environments for you and prefers a declarative approach to dependencies.
","path":["Guides","Running scripts"],"tags":[]},{"location":"guides/scripts/#running-a-script-without-dependencies","level":2,"title":"Running a script without dependencies","text":"If your script has no dependencies, you can execute it with uv run:
example.pyprint(\"Hello world\")\n
$ uv run example.py\nHello world\n
Similarly, if your script depends on a module in the standard library, there's nothing more to do:
example.pyimport os\n\nprint(os.path.expanduser(\"~\"))\n
$ uv run example.py\n/Users/astral\n
Arguments may be provided to the script:
example.pyimport sys\n\nprint(\" \".join(sys.argv[1:]))\n
$ uv run example.py test\ntest\n\n$ uv run example.py hello world!\nhello world!\n
Additionally, your script can be read directly from stdin:
$ echo 'print(\"hello world!\")' | uv run -\n
Or, if your shell supports here-documents:
uv run - <<EOF\nprint(\"hello world!\")\nEOF\n
Note that if you use uv run in a project, i.e., a directory with a pyproject.toml, it will install the current project before running the script. If your script does not depend on the project, use the --no-project flag to skip this:
$ # Note: the `--no-project` flag must be provided _before_ the script name.\n$ uv run --no-project example.py\n
See the projects guide for more details on working in projects.
","path":["Guides","Running scripts"],"tags":[]},{"location":"guides/scripts/#running-a-script-with-dependencies","level":2,"title":"Running a script with dependencies","text":"When your script requires other packages, they must be installed into the environment that the script runs in. uv prefers to create these environments on-demand instead of using a long-lived virtual environment with manually managed dependencies. This requires explicit declaration of dependencies that are required for the script. Generally, it's recommended to use a project or inline metadata to declare dependencies, but uv supports requesting dependencies per invocation as well.
For example, the following script requires rich.
example.pyimport time\nfrom rich.progress import track\n\nfor i in track(range(20), description=\"For example:\"):\n time.sleep(0.05)\n
If executed without specifying a dependency, this script will fail:
$ uv run --no-project example.py\nTraceback (most recent call last):\n File \"/Users/astral/example.py\", line 2, in <module>\n from rich.progress import track\nModuleNotFoundError: No module named 'rich'\n
Request the dependency using the --with option:
$ uv run --with rich example.py\nFor example: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:01\n
Constraints can be added to the requested dependency if specific versions are needed:
$ uv run --with 'rich>12,<13' example.py\n
Multiple dependencies can be requested by repeating with --with option.
Note that if uv run is used in a project, these dependencies will be included in addition to the project's dependencies. To opt-out of this behavior, use the --no-project flag.
","path":["Guides","Running scripts"],"tags":[]},{"location":"guides/scripts/#creating-a-python-script","level":2,"title":"Creating a Python script","text":"Python recently added a standard format for inline script metadata. It allows for selecting Python versions and defining dependencies. Use uv init --script to initialize scripts with the inline metadata:
$ uv init --script example.py --python 3.12\n
","path":["Guides","Running scripts"],"tags":[]},{"location":"guides/scripts/#declaring-script-dependencies","level":2,"title":"Declaring script dependencies","text":"The inline metadata format allows the dependencies for a script to be declared in the script itself.
uv supports adding and updating inline script metadata for you. Use uv add --script to declare the dependencies for the script:
$ uv add --script example.py 'requests<3' 'rich'\n
This will add a script section at the top of the script declaring the dependencies using TOML:
example.py# /// script\n# dependencies = [\n# \"requests<3\",\n# \"rich\",\n# ]\n# ///\n\nimport requests\nfrom rich.pretty import pprint\n\nresp = requests.get(\"https://peps.python.org/api/peps.json\")\ndata = resp.json()\npprint([(k, v[\"title\"]) for k, v in data.items()][:10])\n
uv will automatically create an environment with the dependencies necessary to run the script, e.g.:
$ uv run example.py\n[\n│ ('1', 'PEP Purpose and Guidelines'),\n│ ('2', 'Procedure for Adding New Modules'),\n│ ('3', 'Guidelines for Handling Bug Reports'),\n│ ('4', 'Deprecation of Standard Modules'),\n│ ('5', 'Guidelines for Language Evolution'),\n│ ('6', 'Bug Fix Releases'),\n│ ('7', 'Style Guide for C Code'),\n│ ('8', 'Style Guide for Python Code'),\n│ ('9', 'Sample Plaintext PEP Template'),\n│ ('10', 'Voting Guidelines')\n]\n
Important
When using inline script metadata, even if uv run is used in a project, the project's dependencies will be ignored. The --no-project flag is not required.
uv also respects Python version requirements:
example.py# /// script\n# requires-python = \">=3.12\"\n# dependencies = []\n# ///\n\n# Use some syntax added in Python 3.12\ntype Point = tuple[float, float]\nprint(Point)\n
Note
The dependencies field must be provided even if empty.
uv run will search for and use the required Python version. The Python version will download if it is not installed — see the documentation on Python versions for more details.
","path":["Guides","Running scripts"],"tags":[]},{"location":"guides/scripts/#using-a-shebang-to-create-an-executable-file","level":2,"title":"Using a shebang to create an executable file","text":"A shebang can be added to make a script executable without using uv run — this makes it easy to run scripts that are on your PATH or in the current folder.
For example, create a file called greet with the following contents
greet#!/usr/bin/env -S uv run --script\n\nprint(\"Hello, world!\")\n
Ensure that your script is executable, e.g., with chmod +x greet, then run the script:
$ ./greet\nHello, world!\n
Declaration of dependencies is also supported in this context, for example:
example#!/usr/bin/env -S uv run --script\n#\n# /// script\n# requires-python = \">=3.12\"\n# dependencies = [\"httpx\"]\n# ///\n\nimport httpx\n\nprint(httpx.get(\"https://example.com\"))\n
","path":["Guides","Running scripts"],"tags":[]},{"location":"guides/scripts/#using-alternative-package-indexes","level":2,"title":"Using alternative package indexes","text":"If you wish to use an alternative package index to resolve dependencies, you can provide the index with the --index option:
$ uv add --index \"https://example.com/simple\" --script example.py 'requests<3' 'rich'\n
This will include the package data in the inline metadata:
# [[tool.uv.index]]\n# url = \"https://example.com/simple\"\n
If you require authentication to access the package index, then please refer to the package index documentation.
","path":["Guides","Running scripts"],"tags":[]},{"location":"guides/scripts/#locking-dependencies","level":2,"title":"Locking dependencies","text":"uv supports locking dependencies for PEP 723 scripts using the uv.lock file format. Unlike with projects, scripts must be explicitly locked using uv lock:
$ uv lock --script example.py\n
Running uv lock --script will create a .lock file adjacent to the script (e.g., example.py.lock).
Once locked, subsequent operations like uv run --script, uv add --script, uv export --script, and uv tree --script will reuse the locked dependencies, updating the lockfile if necessary.
If no such lockfile is present, commands like uv export --script will still function as expected, but will not create a lockfile.
","path":["Guides","Running scripts"],"tags":[]},{"location":"guides/scripts/#improving-reproducibility","level":2,"title":"Improving reproducibility","text":"In addition to locking dependencies, uv supports an exclude-newer field in the tool.uv section of inline script metadata to limit uv to only considering distributions released before a specific date. This is useful for improving the reproducibility of your script when run at a later point in time.
The date must be specified as an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z).
example.py# /// script\n# dependencies = [\n# \"requests\",\n# ]\n# [tool.uv]\n# exclude-newer = \"2023-10-16T00:00:00Z\"\n# ///\n\nimport requests\n\nprint(requests.__version__)\n
","path":["Guides","Running scripts"],"tags":[]},{"location":"guides/scripts/#using-different-python-versions","level":2,"title":"Using different Python versions","text":"uv allows arbitrary Python versions to be requested on each script invocation, for example:
example.pyimport sys\n\nprint(\".\".join(map(str, sys.version_info[:3])))\n
$ # Use the default Python version, may differ on your machine\n$ uv run example.py\n3.12.6\n
$ # Use a specific Python version\n$ uv run --python 3.10 example.py\n3.10.15\n
See the Python version request documentation for more details on requesting Python versions.
","path":["Guides","Running scripts"],"tags":[]},{"location":"guides/scripts/#using-gui-scripts","level":2,"title":"Using GUI scripts","text":"On Windows uv will run your script ending with .pyw extension using pythonw:
example.pywfrom tkinter import Tk, ttk\n\nroot = Tk()\nroot.title(\"uv\")\nfrm = ttk.Frame(root, padding=10)\nfrm.grid()\nttk.Label(frm, text=\"Hello World\").grid(column=0, row=0)\nroot.mainloop()\n
PS> uv run example.pyw\n
Similarly, it works with dependencies as well:
example_pyqt.pywimport sys\nfrom PyQt5.QtWidgets import QApplication, QWidget, QLabel, QGridLayout\n\napp = QApplication(sys.argv)\nwidget = QWidget()\ngrid = QGridLayout()\n\ntext_label = QLabel()\ntext_label.setText(\"Hello World!\")\ngrid.addWidget(text_label)\n\nwidget.setLayout(grid)\nwidget.setGeometry(100, 100, 200, 50)\nwidget.setWindowTitle(\"uv\")\nwidget.show()\nsys.exit(app.exec_())\n
PS> uv run --with PyQt5 example_pyqt.pyw\n
","path":["Guides","Running scripts"],"tags":[]},{"location":"guides/scripts/#next-steps","level":2,"title":"Next steps","text":"To learn more about uv run, see the command reference.
Or, read on to learn how to run and install tools with uv.
","path":["Guides","Running scripts"],"tags":[]},{"location":"guides/tools/","level":1,"title":"Using tools","text":"Many Python packages provide applications that can be used as tools. uv has specialized support for easily invoking and installing tools.
","path":["Guides","Using tools"],"tags":[]},{"location":"guides/tools/#running-tools","level":2,"title":"Running tools","text":"The uvx command invokes a tool without installing it.
For example, to run ruff:
$ uvx ruff\n
Note
This is exactly equivalent to:
$ uv tool run ruff\n
uvx is provided as an alias for convenience.
Arguments can be provided after the tool name:
$ uvx pycowsay hello from uv\n\n -------------\n< hello from uv >\n -------------\n \\ ^__^\n \\ (oo)\\_______\n (__)\\ )\\/\\\n ||----w |\n || ||\n
Tools are installed into temporary, isolated environments when using uvx.
Note
If you are running a tool in a project and the tool requires that your project is installed, e.g., when using pytest or mypy, you'll want to use uv run instead of uvx. Otherwise, the tool will be run in a virtual environment that is isolated from your project.
If your project has a flat structure, e.g., instead of using a src directory for modules, the project itself does not need to be installed and uvx is fine. In this case, using uv run is only beneficial if you want to pin the version of the tool in the project's dependencies.
","path":["Guides","Using tools"],"tags":[]},{"location":"guides/tools/#commands-with-different-package-names","level":2,"title":"Commands with different package names","text":"When uvx ruff is invoked, uv installs the ruff package which provides the ruff command. However, sometimes the package and command names differ.
The --from option can be used to invoke a command from a specific package, e.g., http which is provided by httpie:
$ uvx --from httpie http\n
","path":["Guides","Using tools"],"tags":[]},{"location":"guides/tools/#requesting-specific-versions","level":2,"title":"Requesting specific versions","text":"To run a tool at a specific version, use command@<version>:
$ uvx ruff@0.3.0 check\n
To run a tool at the latest version, use command@latest:
$ uvx ruff@latest check\n
The --from option can also be used to specify package versions, as above:
$ uvx --from 'ruff==0.3.0' ruff check\n
Or, to constrain to a range of versions:
$ uvx --from 'ruff>0.2.0,<0.3.0' ruff check\n
Note the @ syntax cannot be used for anything other than an exact version.
","path":["Guides","Using tools"],"tags":[]},{"location":"guides/tools/#requesting-extras","level":2,"title":"Requesting extras","text":"The --from option can be used to run a tool with extras:
$ uvx --from 'mypy[faster-cache,reports]' mypy --xml-report mypy_report\n
This can also be combined with version selection:
$ uvx --from 'mypy[faster-cache,reports]==1.13.0' mypy --xml-report mypy_report\n
","path":["Guides","Using tools"],"tags":[]},{"location":"guides/tools/#requesting-different-sources","level":2,"title":"Requesting different sources","text":"The --from option can also be used to install from alternative sources.
For example, to pull from git:
$ uvx --from git+https://github.com/httpie/cli httpie\n
You can also pull the latest commit from a specific named branch:
$ uvx --from git+https://github.com/httpie/cli@master httpie\n
Or pull a specific tag:
$ uvx --from git+https://github.com/httpie/cli@3.2.4 httpie\n
Or even a specific commit:
$ uvx --from git+https://github.com/httpie/cli@2843b87 httpie\n
","path":["Guides","Using tools"],"tags":[]},{"location":"guides/tools/#commands-with-plugins","level":2,"title":"Commands with plugins","text":"Additional dependencies can be included, e.g., to include mkdocs-material when running mkdocs:
$ uvx --with mkdocs-material mkdocs --help\n
","path":["Guides","Using tools"],"tags":[]},{"location":"guides/tools/#installing-tools","level":2,"title":"Installing tools","text":"If a tool is used often, it is useful to install it to a persistent environment and add it to the PATH instead of invoking uvx repeatedly.
Tip
uvx is a convenient alias for uv tool run. All of the other commands for interacting with tools require the full uv tool prefix.
To install ruff:
$ uv tool install ruff\n
When a tool is installed, its executables are placed in a bin directory in the PATH which allows the tool to be run without uv. If it's not on the PATH, a warning will be displayed and uv tool update-shell can be used to add it to the PATH.
After installing ruff, it should be available:
$ ruff --version\n
Unlike uv pip install, installing a tool does not make its modules available in the current environment. For example, the following command will fail:
$ python -c \"import ruff\"\n
This isolation is important for reducing interactions and conflicts between dependencies of tools, scripts, and projects.
Unlike uvx, uv tool install operates on a package and will install all executables provided by the tool.
For example, the following will install the http, https, and httpie executables:
$ uv tool install httpie\n
Additionally, package versions can be included without --from:
$ uv tool install 'httpie>0.1.0'\n
And, similarly, for package sources:
$ uv tool install git+https://github.com/httpie/cli\n
As with uvx, installations can include additional packages:
$ uv tool install mkdocs --with mkdocs-material\n
Multiple related executables can be installed together in the same tool environment, using the --with-executables-from flag. For example, the following will install the executables from ansible, plus those ones provided by ansible-core and ansible-lint:
$ uv tool install --with-executables-from ansible-core,ansible-lint ansible\n
","path":["Guides","Using tools"],"tags":[]},{"location":"guides/tools/#upgrading-tools","level":2,"title":"Upgrading tools","text":"To upgrade a tool, use uv tool upgrade:
$ uv tool upgrade ruff\n
Tool upgrades will respect the version constraints provided when installing the tool. For example, uv tool install ruff >=0.3,<0.4 followed by uv tool upgrade ruff will upgrade Ruff to the latest version in the range >=0.3,<0.4.
To instead replace the version constraints, re-install the tool with uv tool install:
$ uv tool install ruff>=0.4\n
To instead upgrade all tools:
$ uv tool upgrade --all\n
","path":["Guides","Using tools"],"tags":[]},{"location":"guides/tools/#requesting-python-versions","level":2,"title":"Requesting Python versions","text":"By default, uv will use your default Python interpreter (the first it finds) when running, installing, or upgrading tools. You can specify the Python interpreter to use with the --python option.
For example, to request a specific Python version when running a tool:
$ uvx --python 3.10 ruff\n
Or, when installing a tool:
$ uv tool install --python 3.10 ruff\n
Or, when upgrading a tool:
$ uv tool upgrade --python 3.10 ruff\n
For more details on requesting Python versions, see the Python version concept page.
","path":["Guides","Using tools"],"tags":[]},{"location":"guides/tools/#legacy-windows-scripts","level":2,"title":"Legacy Windows Scripts","text":"Tools also support running legacy setuptools scripts. These scripts are available via $(uv tool dir)\\<tool-name>\\Scripts when installed.
Currently only legacy scripts with the .ps1, .cmd, and .bat extensions are supported.
For example, below is an example running a Command Prompt script.
$ uv tool run --from nuitka==2.6.7 nuitka.cmd --version\n
In addition, you don't need to specify the extension. uvx will automatically look for files ending in .ps1, .cmd, and .bat in that order of execution on your behalf.
$ uv tool run --from nuitka==2.6.7 nuitka --version\n
","path":["Guides","Using tools"],"tags":[]},{"location":"guides/tools/#next-steps","level":2,"title":"Next steps","text":"To learn more about managing tools with uv, see the Tools concept page and the command reference.
Or, read on to learn how to work on projects.
","path":["Guides","Using tools"],"tags":[]},{"location":"guides/integration/","level":1,"title":"Integration guides","text":"Learn how to integrate uv with other software:
- Using in Docker images
- Using with Jupyter notebooks
- Using with marimo notebooks
- Using with pre-commit
- Using in GitHub Actions
- Using in GitLab CI/CD
- Using with alternative package indexes
- Installing PyTorch
- Building a FastAPI application
- Using with AWS Lambda
- Using with Coiled
Or, explore the concept documentation for comprehensive breakdown of each feature.
","path":["Guides","Integrations","Integration guides"],"tags":[]},{"location":"guides/integration/alternative-indexes/","level":1,"title":"Using alternative package indexes","text":"While uv uses the official Python Package Index (PyPI) by default, it also supports alternative package indexes. Most alternative indexes require various forms of authentication, which require some initial setup.
Important
If using the pip interface, please read the documentation on using multiple indexes in uv — the default behavior is different from pip to prevent dependency confusion attacks, but this means that uv may not find the versions of a package as you'd expect.
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#azure-artifacts","level":2,"title":"Azure Artifacts","text":"uv can install packages from Azure Artifacts, either by using a Personal Access Token (PAT), or using the keyring package.
To use Azure Artifacts, add the index to your project:
pyproject.toml[[tool.uv.index]]\nname = \"private-registry\"\nurl = \"https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/simple/\"\n
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#authenticate-with-an-azure-access-token","level":3,"title":"Authenticate with an Azure access token","text":"If there is a personal access token (PAT) available (e.g., $(System.AccessToken) in an Azure pipeline), credentials can be provided via \"Basic\" HTTP authentication scheme. Include the PAT in the password field of the URL. A username must be included as well, but can be any string.
For example, with the token stored in the $AZURE_ARTIFACTS_TOKEN environment variable, set credentials for the index with:
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=dummy\nexport UV_INDEX_PRIVATE_REGISTRY_PASSWORD=\"$AZURE_ARTIFACTS_TOKEN\"\n
Note
PRIVATE_REGISTRY should match the name of the index defined in your pyproject.toml.
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#authenticate-with-keyring-and-artifacts-keyring","level":3,"title":"Authenticate with keyring and artifacts-keyring","text":"You can also authenticate to Artifacts using keyring package with the artifacts-keyring plugin. Because these two packages are required to authenticate to Azure Artifacts, they must be pre-installed from a source other than Artifacts.
The artifacts-keyring plugin wraps the Azure Artifacts Credential Provider tool. The credential provider supports a few different authentication modes including interactive login — see the tool's documentation for information on configuration.
uv only supports using the keyring package in subprocess mode. The keyring executable must be in the PATH, i.e., installed globally or in the active environment. The keyring CLI requires a username in the URL, and it must be VssSessionToken.
# Pre-install keyring and the Artifacts plugin from the public PyPI\nuv tool install keyring --with artifacts-keyring\n\n# Enable keyring authentication\nexport UV_KEYRING_PROVIDER=subprocess\n\n# Set the username for the index\nexport UV_INDEX_PRIVATE_REGISTRY_USERNAME=VssSessionToken\n
Note
The tool.uv.keyring-provider setting can be used to enable keyring in your uv.toml or pyproject.toml.
Similarly, the username for the index can be added directly to the index URL.
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#publishing-packages-to-azure-artifacts","level":3,"title":"Publishing packages to Azure Artifacts","text":"If you also want to publish your own packages to Azure Artifacts, you can use uv publish as described in the Building and publishing guide.
First, add a publish-url to the index you want to publish packages to. For example:
pyproject.toml[[tool.uv.index]]\nname = \"private-registry\"\nurl = \"https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/simple/\"\npublish-url = \"https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/upload/\"\n
Then, configure credentials (if not using keyring):
$ export UV_PUBLISH_USERNAME=dummy\n$ export UV_PUBLISH_PASSWORD=\"$AZURE_ARTIFACTS_TOKEN\"\n
And publish the package:
$ uv publish --index private-registry\n
To use uv publish without adding the publish-url to the project, you can set UV_PUBLISH_URL:
$ export UV_PUBLISH_URL=https://pkgs.dev.azure.com/<ORGANIZATION>/<PROJECT>/_packaging/<FEED>/pypi/upload/\n$ uv publish\n
Note this method is not preferable because uv cannot check if the package is already published before uploading artifacts.
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#google-artifact-registry","level":2,"title":"Google Artifact Registry","text":"uv can install packages from Google Artifact Registry, either by using an access token, or using the keyring package.
Note
This guide assumes that gcloud CLI is installed and authenticated.
To use Google Artifact Registry, add the index to your project:
pyproject.toml[[tool.uv.index]]\nname = \"private-registry\"\nurl = \"https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/simple/\"\n
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#authenticate-with-a-google-access-token","level":3,"title":"Authenticate with a Google access token","text":"Credentials can be provided via \"Basic\" HTTP authentication scheme. Include access token in the password field of the URL. Username must be oauth2accesstoken, otherwise authentication will fail.
Generate a token with gcloud:
export ARTIFACT_REGISTRY_TOKEN=$(\n gcloud auth application-default print-access-token\n)\n
Note
You might need to pass extra parameters to properly generate the token (like --project), this is a basic example.
Then set credentials for the index with:
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=oauth2accesstoken\nexport UV_INDEX_PRIVATE_REGISTRY_PASSWORD=\"$ARTIFACT_REGISTRY_TOKEN\"\n
Note
PRIVATE_REGISTRY should match the name of the index defined in your pyproject.toml.
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#authenticate-with-keyring-and-keyringsgoogle-artifactregistry-auth","level":3,"title":"Authenticate with keyring and keyrings.google-artifactregistry-auth","text":"You can also authenticate to Artifact Registry using keyring package with the keyrings.google-artifactregistry-auth plugin. Because these two packages are required to authenticate to Artifact Registry, they must be pre-installed from a source other than Artifact Registry.
The keyrings.google-artifactregistry-auth plugin wraps gcloud CLI to generate short-lived access tokens, securely store them in system keyring, and refresh them when they are expired.
uv only supports using the keyring package in subprocess mode. The keyring executable must be in the PATH, i.e., installed globally or in the active environment. The keyring CLI requires a username in the URL and it must be oauth2accesstoken.
# Pre-install keyring and Artifact Registry plugin from the public PyPI\nuv tool install keyring --with keyrings.google-artifactregistry-auth\n\n# Enable keyring authentication\nexport UV_KEYRING_PROVIDER=subprocess\n\n# Set the username for the index\nexport UV_INDEX_PRIVATE_REGISTRY_USERNAME=oauth2accesstoken\n
Note
The tool.uv.keyring-provider setting can be used to enable keyring in your uv.toml or pyproject.toml.
Similarly, the username for the index can be added directly to the index URL.
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#publishing-packages-to-google-artifact-registry","level":3,"title":"Publishing packages to Google Artifact Registry","text":"If you also want to publish your own packages to Google Artifact Registry, you can use uv publish as described in the Building and publishing guide.
First, add a publish-url to the index you want to publish packages to. For example:
pyproject.toml[[tool.uv.index]]\nname = \"private-registry\"\nurl = \"https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/simple/\"\npublish-url = \"https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/\"\n
Then, configure credentials (if not using keyring):
$ export UV_PUBLISH_USERNAME=oauth2accesstoken\n$ export UV_PUBLISH_PASSWORD=\"$ARTIFACT_REGISTRY_TOKEN\"\n
And publish the package:
$ uv publish --index private-registry\n
To use uv publish without adding the publish-url to the project, you can set UV_PUBLISH_URL:
$ export UV_PUBLISH_URL=https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/\n$ uv publish\n
Note this method is not preferable because uv cannot check if the package is already published before uploading artifacts.
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#aws-codeartifact","level":2,"title":"AWS CodeArtifact","text":"uv can install packages from AWS CodeArtifact, either by using an access token, or using the keyring package.
Note
This guide assumes that awscli is installed and authenticated.
The index can be declared like so:
pyproject.toml[[tool.uv.index]]\nname = \"private-registry\"\nurl = \"https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/simple/\"\n
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#authenticate-with-an-aws-access-token","level":3,"title":"Authenticate with an AWS access token","text":"Credentials can be provided via \"Basic\" HTTP authentication scheme. Include access token in the password field of the URL. Username must be aws, otherwise authentication will fail.
Generate a token with awscli:
export AWS_CODEARTIFACT_TOKEN=\"$(\n aws codeartifact get-authorization-token \\\n --domain <DOMAIN> \\\n --domain-owner <ACCOUNT_ID> \\\n --query authorizationToken \\\n --output text\n)\"\n
Note
You might need to pass extra parameters to properly generate the token (like --region), this is a basic example.
Then set credentials for the index with:
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=aws\nexport UV_INDEX_PRIVATE_REGISTRY_PASSWORD=\"$AWS_CODEARTIFACT_TOKEN\"\n
Note
PRIVATE_REGISTRY should match the name of the index defined in your pyproject.toml.
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#authenticate-with-keyring-and-keyringscodeartifact","level":3,"title":"Authenticate with keyring and keyrings.codeartifact","text":"You can also authenticate to Artifact Registry using keyring package with the keyrings.codeartifact plugin. Because these two packages are required to authenticate to Artifact Registry, they must be pre-installed from a source other than Artifact Registry.
The keyrings.codeartifact plugin wraps boto3 to generate short-lived access tokens, securely store them in system keyring, and refresh them when they are expired.
uv only supports using the keyring package in subprocess mode. The keyring executable must be in the PATH, i.e., installed globally or in the active environment. The keyring CLI requires a username in the URL and it must be aws.
# Pre-install keyring and AWS CodeArtifact plugin from the public PyPI\nuv tool install keyring --with keyrings.codeartifact\n\n# Enable keyring authentication\nexport UV_KEYRING_PROVIDER=subprocess\n\n# Set the username for the index\nexport UV_INDEX_PRIVATE_REGISTRY_USERNAME=aws\n
Note
The tool.uv.keyring-provider setting can be used to enable keyring in your uv.toml or pyproject.toml.
Similarly, the username for the index can be added directly to the index URL.
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#publishing-packages-to-aws-codeartifact","level":3,"title":"Publishing packages to AWS CodeArtifact","text":"If you also want to publish your own packages to AWS CodeArtifact, you can use uv publish as described in the Building and publishing guide.
First, add a publish-url to the index you want to publish packages to. For example:
pyproject.toml[[tool.uv.index]]\nname = \"private-registry\"\nurl = \"https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/simple/\"\npublish-url = \"https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/\"\n
Then, configure credentials (if not using keyring):
$ export UV_PUBLISH_USERNAME=aws\n$ export UV_PUBLISH_PASSWORD=\"$AWS_CODEARTIFACT_TOKEN\"\n
And publish the package:
$ uv publish --index private-registry\n
To use uv publish without adding the publish-url to the project, you can set UV_PUBLISH_URL:
$ export UV_PUBLISH_URL=https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/\n$ uv publish\n
Note this method is not preferable because uv cannot check if the package is already published before uploading artifacts.
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#jfrog-artifactory","level":2,"title":"JFrog Artifactory","text":"uv can install packages from JFrog Artifactory, either by using a username and password or a JWT token.
To use it, add the index to your project:
pyproject.toml[[tool.uv.index]]\nname = \"private-registry\"\nurl = \"https://<organization>.jfrog.io/artifactory/api/pypi/<repository>/simple\"\n
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#authenticate-with-username-and-password","level":3,"title":"Authenticate with username and password","text":"$ export UV_INDEX_PRIVATE_REGISTRY_USERNAME=\"<username>\"\n$ export UV_INDEX_PRIVATE_REGISTRY_PASSWORD=\"<password>\"\n
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#authenticate-with-jwt-token","level":3,"title":"Authenticate with JWT token","text":"$ export UV_INDEX_PRIVATE_REGISTRY_USERNAME=\"\"\n$ export UV_INDEX_PRIVATE_REGISTRY_PASSWORD=\"$JFROG_JWT_TOKEN\"\n
Note
Replace PRIVATE_REGISTRY in the environment variable names with the actual index name defined in your pyproject.toml.
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/alternative-indexes/#publishing-packages-to-jfrog-artifactory","level":3,"title":"Publishing packages to JFrog Artifactory","text":"Add a publish-url to your index definition:
pyproject.toml[[tool.uv.index]]\nname = \"private-registry\"\nurl = \"https://<organization>.jfrog.io/artifactory/api/pypi/<repository>/simple\"\npublish-url = \"https://<organization>.jfrog.io/artifactory/api/pypi/<repository>\"\n
Important
If you use --token \"$JFROG_TOKEN\" or UV_PUBLISH_TOKEN with JFrog, you will receive a 401 Unauthorized error as JFrog requires an empty username but uv passes __token__ for as the username when --token is used.
To authenticate, pass your token as the password and set the username to an empty string:
$ uv publish --index <index_name> -u \"\" -p \"$JFROG_TOKEN\"\n
Alternatively, you can set environment variables:
$ export UV_PUBLISH_USERNAME=\"\"\n$ export UV_PUBLISH_PASSWORD=\"$JFROG_TOKEN\"\n$ uv publish --index private-registry\n
Note
The publish environment variables (UV_PUBLISH_USERNAME and UV_PUBLISH_PASSWORD) do not include the index name.
","path":["Guides","Integrations","Using alternative package indexes"],"tags":[]},{"location":"guides/integration/aws-lambda/","level":1,"title":"Using uv with AWS Lambda","text":"AWS Lambda is a serverless computing service that lets you run code without provisioning or managing servers.
You can use uv with AWS Lambda to manage your Python dependencies, build your deployment package, and deploy your Lambda functions.
Tip
Check out the uv-aws-lambda-example project for an example of best practices when using uv to deploy an application to AWS Lambda.
","path":["Guides","Integrations","Using uv with AWS Lambda"],"tags":[]},{"location":"guides/integration/aws-lambda/#getting-started","level":2,"title":"Getting started","text":"To start, assume we have a minimal FastAPI application with the following structure:
project\n├── pyproject.toml\n└── app\n ├── __init__.py\n └── main.py\n
Where the pyproject.toml contains:
pyproject.toml[project]\nname = \"uv-aws-lambda-example\"\nversion = \"0.1.0\"\nrequires-python = \">=3.13\"\ndependencies = [\n # FastAPI is a modern web framework for building APIs with Python.\n \"fastapi\",\n # Mangum is a library that adapts ASGI applications to AWS Lambda and API Gateway.\n \"mangum\",\n]\n\n[dependency-groups]\ndev = [\n # In development mode, include the FastAPI development server.\n \"fastapi[standard]>=0.115\",\n]\n
And the main.py file contains:
app/main.pyimport logging\n\nfrom fastapi import FastAPI\nfrom mangum import Mangum\n\nlogger = logging.getLogger()\nlogger.setLevel(logging.INFO)\n\napp = FastAPI()\nhandler = Mangum(app)\n\n\n@app.get(\"/\")\nasync def root() -> str:\n return \"Hello, world!\"\n
We can run this application locally with:
$ uv run fastapi dev\n
From there, opening http://127.0.0.1:8000/ in a web browser will display \"Hello, world!\"
","path":["Guides","Integrations","Using uv with AWS Lambda"],"tags":[]},{"location":"guides/integration/aws-lambda/#deploying-a-docker-image","level":2,"title":"Deploying a Docker image","text":"To deploy to AWS Lambda, we need to build a container image that includes the application code and dependencies in a single output directory.
We'll follow the principles outlined in the Docker guide (in particular, a multi-stage build) to ensure that the final image is as small and cache-friendly as possible.
In the first stage, we'll populate a single directory with all application code and dependencies. In the second stage, we'll copy this directory over to the final image, omitting the build tools and other unnecessary files.
DockerfileFROM ghcr.io/astral-sh/uv:0.9.8 AS uv\n\n# First, bundle the dependencies into the task root.\nFROM public.ecr.aws/lambda/python:3.13 AS builder\n\n# Enable bytecode compilation, to improve cold-start performance.\nENV UV_COMPILE_BYTECODE=1\n\n# Disable installer metadata, to create a deterministic layer.\nENV UV_NO_INSTALLER_METADATA=1\n\n# Enable copy mode to support bind mount caching.\nENV UV_LINK_MODE=copy\n\n# Bundle the dependencies into the Lambda task root via `uv pip install --target`.\n#\n# Omit any local packages (`--no-emit-workspace`) and development dependencies (`--no-dev`).\n# This ensures that the Docker layer cache is only invalidated when the `pyproject.toml` or `uv.lock`\n# files change, but remains robust to changes in the application code.\nRUN --mount=from=uv,source=/uv,target=/bin/uv \\\n --mount=type=cache,target=/root/.cache/uv \\\n --mount=type=bind,source=uv.lock,target=uv.lock \\\n --mount=type=bind,source=pyproject.toml,target=pyproject.toml \\\n uv export --frozen --no-emit-workspace --no-dev --no-editable -o requirements.txt && \\\n uv pip install -r requirements.txt --target \"${LAMBDA_TASK_ROOT}\"\n\nFROM public.ecr.aws/lambda/python:3.13\n\n# Copy the runtime dependencies from the builder stage.\nCOPY --from=builder ${LAMBDA_TASK_ROOT} ${LAMBDA_TASK_ROOT}\n\n# Copy the application code.\nCOPY ./app ${LAMBDA_TASK_ROOT}/app\n\n# Set the AWS Lambda handler.\nCMD [\"app.main.handler\"]\n
Tip
To deploy to ARM-based AWS Lambda runtimes, replace public.ecr.aws/lambda/python:3.13 with public.ecr.aws/lambda/python:3.13-arm64.
We can build the image with, e.g.:
$ uv lock\n$ docker build -t fastapi-app .\n
The core benefits of this Dockerfile structure are as follows:
- Minimal image size. By using a multi-stage build, we can ensure that the final image only includes the application code and dependencies. For example, the uv binary itself is not included in the final image.
- Maximal cache reuse. By installing application dependencies separately from the application code, we can ensure that the Docker layer cache is only invalidated when the dependencies change.
Concretely, rebuilding the image after modifying the application source code can reuse the cached layers, resulting in millisecond builds:
=> [internal] load build definition from Dockerfile 0.0s\n => => transferring dockerfile: 1.31kB 0.0s\n => [internal] load metadata for public.ecr.aws/lambda/python:3.13 0.3s\n => [internal] load metadata for ghcr.io/astral-sh/uv:latest 0.3s\n => [internal] load .dockerignore 0.0s\n => => transferring context: 106B 0.0s\n => [uv 1/1] FROM ghcr.io/astral-sh/uv:latest@sha256:ea61e006cfec0e8d81fae901ad703e09d2c6cf1aa58abcb6507d124b50286f 0.0s\n => [builder 1/2] FROM public.ecr.aws/lambda/python:3.13@sha256:f5b51b377b80bd303fe8055084e2763336ea8920d12955b23ef 0.0s\n => [internal] load build context 0.0s\n => => transferring context: 185B 0.0s\n => CACHED [builder 2/2] RUN --mount=from=uv,source=/uv,target=/bin/uv --mount=type=cache,target=/root/.cache/u 0.0s\n => CACHED [stage-2 2/3] COPY --from=builder /var/task /var/task 0.0s\n => CACHED [stage-2 3/3] COPY ./app /var/task 0.0s\n => exporting to image 0.0s\n => => exporting layers 0.0s\n => => writing image sha256:6f8f9ef715a7cda466b677a9df4046ebbb90c8e88595242ade3b4771f547652d 0.0\n
After building, we can push the image to Elastic Container Registry (ECR) with, e.g.:
$ aws ecr get-login-password --region region | docker login --username AWS --password-stdin aws_account_id.dkr.ecr.region.amazonaws.com\n$ docker tag fastapi-app:latest aws_account_id.dkr.ecr.region.amazonaws.com/fastapi-app:latest\n$ docker push aws_account_id.dkr.ecr.region.amazonaws.com/fastapi-app:latest\n
Finally, we can deploy the image to AWS Lambda using the AWS Management Console or the AWS CLI, e.g.:
$ aws lambda create-function \\\n --function-name myFunction \\\n --package-type Image \\\n --code ImageUri=aws_account_id.dkr.ecr.region.amazonaws.com/fastapi-app:latest \\\n --role arn:aws:iam::111122223333:role/my-lambda-role\n
Where the execution role is created via:
$ aws iam create-role \\\n --role-name my-lambda-role \\\n --assume-role-policy-document '{\"Version\": \"2012-10-17\", \"Statement\": [{ \"Effect\": \"Allow\", \"Principal\": {\"Service\": \"lambda.amazonaws.com\"}, \"Action\": \"sts:AssumeRole\"}]}'\n
Or, update an existing function with:
$ aws lambda update-function-code \\\n --function-name myFunction \\\n --image-uri aws_account_id.dkr.ecr.region.amazonaws.com/fastapi-app:latest \\\n --publish\n
To test the Lambda, we can invoke it via the AWS Management Console or the AWS CLI, e.g.:
$ aws lambda invoke \\\n --function-name myFunction \\\n --payload file://event.json \\\n --cli-binary-format raw-in-base64-out \\\n response.json\n{\n \"StatusCode\": 200,\n \"ExecutedVersion\": \"$LATEST\"\n}\n
Where event.json contains the event payload to pass to the Lambda function:
event.json{\n \"httpMethod\": \"GET\",\n \"path\": \"/\",\n \"requestContext\": {},\n \"version\": \"1.0\"\n}\n
And response.json contains the response from the Lambda function:
response.json{\n \"statusCode\": 200,\n \"headers\": {\n \"content-length\": \"14\",\n \"content-type\": \"application/json\"\n },\n \"multiValueHeaders\": {},\n \"body\": \"\\\"Hello, world!\\\"\",\n \"isBase64Encoded\": false\n}\n
For details, see the AWS Lambda documentation.
","path":["Guides","Integrations","Using uv with AWS Lambda"],"tags":[]},{"location":"guides/integration/aws-lambda/#workspace-support","level":3,"title":"Workspace support","text":"If a project includes local dependencies (e.g., via Workspaces), those too must be included in the deployment package.
We'll start by extending the above example to include a dependency on a locally-developed library named library.
First, we'll create the library itself:
$ uv init --lib library\n$ uv add ./library\n
Running uv init within the project directory will automatically convert project to a workspace and add library as a workspace member:
pyproject.toml[project]\nname = \"uv-aws-lambda-example\"\nversion = \"0.1.0\"\nrequires-python = \">=3.13\"\ndependencies = [\n # FastAPI is a modern web framework for building APIs with Python.\n \"fastapi\",\n # A local library.\n \"library\",\n # Mangum is a library that adapts ASGI applications to AWS Lambda and API Gateway.\n \"mangum\",\n]\n\n[dependency-groups]\ndev = [\n # In development mode, include the FastAPI development server.\n \"fastapi[standard]\",\n]\n\n[tool.uv.workspace]\nmembers = [\"library\"]\n\n[tool.uv.sources]\nlib = { workspace = true }\n
By default, uv init --lib will create a package that exports a hello function. We'll modify the application source code to call that function:
app/main.pyimport logging\n\nfrom fastapi import FastAPI\nfrom mangum import Mangum\n\nfrom library import hello\n\nlogger = logging.getLogger()\nlogger.setLevel(logging.INFO)\n\napp = FastAPI()\nhandler = Mangum(app)\n\n\n@app.get(\"/\")\nasync def root() -> str:\n return hello()\n
We can run the modified application locally with:
$ uv run fastapi dev\n
And confirm that opening http://127.0.0.1:8000/ in a web browser displays, \"Hello from library!\" (instead of \"Hello, World!\")
Finally, we'll update the Dockerfile to include the local library in the deployment package:
DockerfileFROM ghcr.io/astral-sh/uv:0.9.8 AS uv\n\n# First, bundle the dependencies into the task root.\nFROM public.ecr.aws/lambda/python:3.13 AS builder\n\n# Enable bytecode compilation, to improve cold-start performance.\nENV UV_COMPILE_BYTECODE=1\n\n# Disable installer metadata, to create a deterministic layer.\nENV UV_NO_INSTALLER_METADATA=1\n\n# Enable copy mode to support bind mount caching.\nENV UV_LINK_MODE=copy\n\n# Bundle the dependencies into the Lambda task root via `uv pip install --target`.\n#\n# Omit any local packages (`--no-emit-workspace`) and development dependencies (`--no-dev`).\n# This ensures that the Docker layer cache is only invalidated when the `pyproject.toml` or `uv.lock`\n# files change, but remains robust to changes in the application code.\nRUN --mount=from=uv,source=/uv,target=/bin/uv \\\n --mount=type=cache,target=/root/.cache/uv \\\n --mount=type=bind,source=uv.lock,target=uv.lock \\\n --mount=type=bind,source=pyproject.toml,target=pyproject.toml \\\n uv export --frozen --no-emit-workspace --no-dev --no-editable -o requirements.txt && \\\n uv pip install -r requirements.txt --target \"${LAMBDA_TASK_ROOT}\"\n\n# If you have a workspace, copy it over and install it too.\n#\n# By omitting `--no-emit-workspace`, `library` will be copied into the task root. Using a separate\n# `RUN` command ensures that all third-party dependencies are cached separately and remain\n# robust to changes in the workspace.\nRUN --mount=from=uv,source=/uv,target=/bin/uv \\\n --mount=type=cache,target=/root/.cache/uv \\\n --mount=type=bind,source=uv.lock,target=uv.lock \\\n --mount=type=bind,source=pyproject.toml,target=pyproject.toml \\\n --mount=type=bind,source=library,target=library \\\n uv export --frozen --no-dev --no-editable -o requirements.txt && \\\n uv pip install -r requirements.txt --target \"${LAMBDA_TASK_ROOT}\"\n\nFROM public.ecr.aws/lambda/python:3.13\n\n# Copy the runtime dependencies from the builder stage.\nCOPY --from=builder ${LAMBDA_TASK_ROOT} ${LAMBDA_TASK_ROOT}\n\n# Copy the application code.\nCOPY ./app ${LAMBDA_TASK_ROOT}/app\n\n# Set the AWS Lambda handler.\nCMD [\"app.main.handler\"]\n
Tip
To deploy to ARM-based AWS Lambda runtimes, replace public.ecr.aws/lambda/python:3.13 with public.ecr.aws/lambda/python:3.13-arm64.
From there, we can build and deploy the updated image as before.
","path":["Guides","Integrations","Using uv with AWS Lambda"],"tags":[]},{"location":"guides/integration/aws-lambda/#deploying-a-zip-archive","level":2,"title":"Deploying a zip archive","text":"AWS Lambda also supports deployment via zip archives. For simple applications, zip archives can be a more straightforward and efficient deployment method than Docker images; however, zip archives are limited to 250 MB in size.
Returning to the FastAPI example, we can bundle the application dependencies into a local directory for AWS Lambda via:
$ uv export --frozen --no-dev --no-editable -o requirements.txt\n$ uv pip install \\\n --no-installer-metadata \\\n --no-compile-bytecode \\\n --python-platform x86_64-manylinux2014 \\\n --python 3.13 \\\n --target packages \\\n -r requirements.txt\n
Tip
To deploy to ARM-based AWS Lambda runtimes, replace x86_64-manylinux2014 with aarch64-manylinux2014.
Following the AWS Lambda documentation, we can then bundle these dependencies into a zip as follows:
$ cd packages\n$ zip -r ../package.zip .\n$ cd ..\n
Finally, we can add the application code to the zip archive:
$ zip -r package.zip app\n
We can then deploy the zip archive to AWS Lambda via the AWS Management Console or the AWS CLI, e.g.:
$ aws lambda create-function \\\n --function-name myFunction \\\n --runtime python3.13 \\\n --zip-file fileb://package.zip \\\n --handler app.main.handler \\\n --role arn:aws:iam::111122223333:role/service-role/my-lambda-role\n
Where the execution role is created via:
$ aws iam create-role \\\n --role-name my-lambda-role \\\n --assume-role-policy-document '{\"Version\": \"2012-10-17\", \"Statement\": [{ \"Effect\": \"Allow\", \"Principal\": {\"Service\": \"lambda.amazonaws.com\"}, \"Action\": \"sts:AssumeRole\"}]}'\n
Or, update an existing function with:
$ aws lambda update-function-code \\\n --function-name myFunction \\\n --zip-file fileb://package.zip\n
Note
By default, the AWS Management Console assumes a Lambda entrypoint of lambda_function.lambda_handler. If your application uses a different entrypoint, you'll need to modify it in the AWS Management Console. For example, the above FastAPI application uses app.main.handler.
To test the Lambda, we can invoke it via the AWS Management Console or the AWS CLI, e.g.:
$ aws lambda invoke \\\n --function-name myFunction \\\n --payload file://event.json \\\n --cli-binary-format raw-in-base64-out \\\n response.json\n{\n \"StatusCode\": 200,\n \"ExecutedVersion\": \"$LATEST\"\n}\n
Where event.json contains the event payload to pass to the Lambda function:
event.json{\n \"httpMethod\": \"GET\",\n \"path\": \"/\",\n \"requestContext\": {},\n \"version\": \"1.0\"\n}\n
And response.json contains the response from the Lambda function:
response.json{\n \"statusCode\": 200,\n \"headers\": {\n \"content-length\": \"14\",\n \"content-type\": \"application/json\"\n },\n \"multiValueHeaders\": {},\n \"body\": \"\\\"Hello, world!\\\"\",\n \"isBase64Encoded\": false\n}\n
","path":["Guides","Integrations","Using uv with AWS Lambda"],"tags":[]},{"location":"guides/integration/aws-lambda/#using-a-lambda-layer","level":3,"title":"Using a Lambda layer","text":"AWS Lambda also supports the deployment of multiple composed Lambda layers when working with zip archives. These layers are conceptually similar to layers in a Docker image, allowing you to separate application code from dependencies.
In particular, we can create a lambda layer for application dependencies and attach it to the Lambda function, separate from the application code itself. This setup can improve cold-start performance for application updates, as the dependencies layer can be reused across deployments.
To create a Lambda layer, we'll follow similar steps, but create two separate zip archives: one for the application code and one for the application dependencies.
First, we'll create the dependency layer. Lambda layers are expected to follow a slightly different structure, so we'll use --prefix rather than --target:
$ uv export --frozen --no-dev --no-editable -o requirements.txt\n$ uv pip install \\\n --no-installer-metadata \\\n --no-compile-bytecode \\\n --python-platform x86_64-manylinux2014 \\\n --python 3.13 \\\n --prefix packages \\\n -r requirements.txt\n
We'll then zip the dependencies in adherence with the expected layout for Lambda layers:
$ mkdir python\n$ cp -r packages/lib python/\n$ zip -r layer_content.zip python\n
Tip
To generate deterministic zip archives, consider passing the -X flag to zip to exclude extended attributes and file system metadata.
And publish the Lambda layer:
$ aws lambda publish-layer-version --layer-name dependencies-layer \\\n --zip-file fileb://layer_content.zip \\\n --compatible-runtimes python3.13 \\\n --compatible-architectures \"x86_64\"\n
We can then create the Lambda function as in the previous example, omitting the dependencies:
$ # Zip the application code.\n$ zip -r app.zip app\n\n$ # Create the Lambda function.\n$ aws lambda create-function \\\n --function-name myFunction \\\n --runtime python3.13 \\\n --zip-file fileb://app.zip \\\n --handler app.main.handler \\\n --role arn:aws:iam::111122223333:role/service-role/my-lambda-role\n
Finally, we can attach the dependencies layer to the Lambda function, using the ARN returned by the publish-layer-version step:
$ aws lambda update-function-configuration --function-name myFunction \\\n --cli-binary-format raw-in-base64-out \\\n --layers \"arn:aws:lambda:region:111122223333:layer:dependencies-layer:1\"\n
When the application dependencies change, the layer can be updated independently of the application by republishing the layer and updating the Lambda function configuration:
$ # Update the dependencies in the layer.\n$ aws lambda publish-layer-version --layer-name dependencies-layer \\\n --zip-file fileb://layer_content.zip \\\n --compatible-runtimes python3.13 \\\n --compatible-architectures \"x86_64\"\n\n$ # Update the Lambda function configuration.\n$ aws lambda update-function-configuration --function-name myFunction \\\n --cli-binary-format raw-in-base64-out \\\n --layers \"arn:aws:lambda:region:111122223333:layer:dependencies-layer:2\"\n
","path":["Guides","Integrations","Using uv with AWS Lambda"],"tags":[]},{"location":"guides/integration/coiled/","level":1,"title":"Using uv with Coiled","text":"Coiled is a serverless, UX-focused cloud computing platform that makes it easy to run code on cloud hardware (AWS, GCP, and Azure).
This guide shows how to run Python scripts on the cloud using uv for dependency management and Coiled for cloud deployment.
","path":["Guides","Integrations","Using uv with Coiled"],"tags":[]},{"location":"guides/integration/coiled/#managing-script-dependencies-with-uv","level":2,"title":"Managing script dependencies with uv","text":"Note
We'll use this concrete example throughout this guide, but any Python script can be used with uv and Coiled.
We'll use the following script as an example:
process.py# /// script\n# requires-python = \">=3.12\"\n# dependencies = [\n# \"pandas\",\n# \"pyarrow\",\n# \"s3fs\",\n# ]\n# ///\n\nimport pandas as pd\n\ndf = pd.read_parquet(\n \"s3://coiled-data/uber/part.0.parquet\",\n storage_options={\"anon\": True},\n)\nprint(df.head())\n
The script uses pandas to load a Parquet file hosted in a public bucket on S3, then prints the first few rows. It uses inline script metadata to enumerate its dependencies.
When running this script locally, e.g., with:
$ uv run process.py\n
uv will automatically create a virtual environment and installs its dependencies.
To learn more about using inline script metadata with uv, see the script guide.
","path":["Guides","Integrations","Using uv with Coiled"],"tags":[]},{"location":"guides/integration/coiled/#running-scripts-on-the-cloud-with-coiled","level":2,"title":"Running scripts on the cloud with Coiled","text":"Using inline script metadata makes the script fully self-contained: it includes the information that is needed to run it. This makes it easier to run on other machines, like a machine in the cloud.
There are many use cases where resources beyond what's available on a local workstation are needed, e.g.:
- Processing large amounts of cloud-hosted data
- Needing accelerated hardware like GPUs or a big machine with more memory
- Running the same script with hundreds or thousands of different inputs, in parallel
Coiled makes it simple to run code on cloud hardware.
First, authenticate with Coiled using coiled login :
$ uvx coiled login\n
You'll be prompted to create a Coiled account if you don't already have one — it's free to start using Coiled.
To instruct Coiled to run the script on a virtual machine on AWS, add two comments to the top:
process.py# COILED container ghcr.io/astral-sh/uv:debian-slim\n# COILED region us-east-2\n\n# /// script\n# requires-python = \">=3.12\"\n# dependencies = [\n# \"pandas\",\n# \"pyarrow\",\n# \"s3fs\",\n# ]\n# ///\n\nimport pandas as pd\n\ndf = pd.read_parquet(\n \"s3://coiled-data/uber/part.0.parquet\",\n storage_options={\"anon\": True},\n)\nprint(df.head())\n
Tip
While Coiled supports AWS, GCP, and Azure, this example assumes AWS is being used (see the region option above). If you're new to Coiled, you'll automatically have access to a free account running on AWS. If you're not running on AWS, you can either use a valid region for your cloud provider or remove the region line above.
The comments tell Coiled to use the official uv Docker image when running the script (ensuring uv is available) and to run in the us-east-2 region on AWS (where this example data file happens to live) to avoid any data egress.
To submit a batch job for Coiled to run, use coiled batch run to execute the uv run command in the cloud:
$ uvx coiled batch run \\\n uv run process.py\n
The same process that previously ran locally is now running on a remote cloud VM on AWS.
You can monitor the progress of the batch job in the UI at cloud.coiled.io or from the terminal using the coiled batch status, coiled batch wait, and coiled batch logs commands.
Note there's additional configuration we could have specified, e.g., the instance type (the default is a 4-core virtual machine with 16 GiB of memory), disk size, whether to use spot instance, and more. See the Coiled Batch documentation for more details.
For more details on Coiled, and how it can help with other use cases, see the Coiled documentation.
","path":["Guides","Integrations","Using uv with Coiled"],"tags":[]},{"location":"guides/integration/dependency-bots/","level":1,"title":"Dependency bots","text":"It is considered best practice to regularly update dependencies, to avoid being exposed to vulnerabilities, limit incompatibilities between dependencies, and avoid complex upgrades when upgrading from a too old version. A variety of tools can help staying up-to-date by creating automated pull requests. Several of them support uv, or have work underway to support it.
","path":["Guides","Integrations","Using uv with dependency bots"],"tags":[]},{"location":"guides/integration/dependency-bots/#renovate","level":2,"title":"Renovate","text":"uv is supported by Renovate.
","path":["Guides","Integrations","Using uv with dependency bots"],"tags":[]},{"location":"guides/integration/dependency-bots/#uvlock-output","level":3,"title":"uv.lock output","text":"Renovate uses the presence of a uv.lock file to determine that uv is used for managing dependencies, and will suggest upgrades to project dependencies, optional dependencies and development dependencies. Renovate will update both the pyproject.toml and uv.lock files.
The lockfile can also be refreshed on a regular basis (for instance to update transitive dependencies) by enabling the lockFileMaintenance option:
renovate.json5{\n $schema: \"https://docs.renovatebot.com/renovate-schema.json\",\n lockFileMaintenance: {\n enabled: true,\n },\n}\n
","path":["Guides","Integrations","Using uv with dependency bots"],"tags":[]},{"location":"guides/integration/dependency-bots/#inline-script-metadata","level":3,"title":"Inline script metadata","text":"Renovate supports updating dependencies defined using script inline metadata.
Since it cannot automatically detect which Python files use script inline metadata, their locations need to be explicitly defined using fileMatch, like so:
renovate.json5{\n $schema: \"https://docs.renovatebot.com/renovate-schema.json\",\n pep723: {\n fileMatch: [\n \"scripts/generate_docs\\\\.py\",\n \"scripts/run_server\\\\.py\",\n ],\n },\n}\n
","path":["Guides","Integrations","Using uv with dependency bots"],"tags":[]},{"location":"guides/integration/dependency-bots/#dependabot","level":2,"title":"Dependabot","text":"Dependabot has announced support for uv, but there are some use cases that are not yet working. See astral-sh/uv#2512 for updates.
Dependabot supports updating uv.lock files. To enable it, add the uv package-ecosystem to your updates list in the dependabot.yml:
dependabot.ymlversion: 2\n\nupdates:\n - package-ecosystem: \"uv\"\n directory: \"/\"\n schedule:\n interval: \"weekly\"\n
","path":["Guides","Integrations","Using uv with dependency bots"],"tags":[]},{"location":"guides/integration/docker/","level":1,"title":"Using uv in Docker","text":"","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#getting-started","level":2,"title":"Getting started","text":"Tip
Check out the uv-docker-example project for an example of best practices when using uv to build an application in Docker.
uv provides both distroless Docker images, which are useful for copying uv binaries into your own image builds, and images derived from popular base images, which are useful for using uv in a container. The distroless images do not contain anything but the uv binaries. In contrast, the derived images include an operating system with uv pre-installed.
As an example, to run uv in a container using a Debian-based image:
$ docker run --rm -it ghcr.io/astral-sh/uv:debian uv --help\n
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#available-images","level":3,"title":"Available images","text":"The following distroless images are available:
ghcr.io/astral-sh/uv:latestghcr.io/astral-sh/uv:{major}.{minor}.{patch}, e.g., ghcr.io/astral-sh/uv:0.9.8ghcr.io/astral-sh/uv:{major}.{minor}, e.g., ghcr.io/astral-sh/uv:0.8 (the latest patch version)
And the following derived images are available:
- Based on
alpine:3.22: ghcr.io/astral-sh/uv:alpineghcr.io/astral-sh/uv:alpine3.22
- Based on
alpine:3.21: ghcr.io/astral-sh/uv:alpine3.21
- Based on
debian:trixie-slim: ghcr.io/astral-sh/uv:debian-slimghcr.io/astral-sh/uv:trixie-slim
- Based on
debian:bookworm-slim: ghcr.io/astral-sh/uv:bookworm-slim
- Based on
buildpack-deps:trixie: ghcr.io/astral-sh/uv:debianghcr.io/astral-sh/uv:trixie
- Based on
buildpack-deps:bookworm: ghcr.io/astral-sh/uv:bookworm
- Based on
python3.x-alpine: ghcr.io/astral-sh/uv:python3.14-alpineghcr.io/astral-sh/uv:python3.13-alpineghcr.io/astral-sh/uv:python3.12-alpineghcr.io/astral-sh/uv:python3.11-alpineghcr.io/astral-sh/uv:python3.10-alpineghcr.io/astral-sh/uv:python3.9-alpineghcr.io/astral-sh/uv:python3.8-alpine
- Based on
python3.x-trixie: ghcr.io/astral-sh/uv:python3.14-trixieghcr.io/astral-sh/uv:python3.13-trixieghcr.io/astral-sh/uv:python3.12-trixieghcr.io/astral-sh/uv:python3.11-trixieghcr.io/astral-sh/uv:python3.10-trixieghcr.io/astral-sh/uv:python3.9-trixie
- Based on
python3.x-slim-trixie: ghcr.io/astral-sh/uv:python3.14-trixie-slimghcr.io/astral-sh/uv:python3.13-trixie-slimghcr.io/astral-sh/uv:python3.12-trixie-slimghcr.io/astral-sh/uv:python3.11-trixie-slimghcr.io/astral-sh/uv:python3.10-trixie-slimghcr.io/astral-sh/uv:python3.9-trixie-slim
- Based on
python3.x-bookworm: ghcr.io/astral-sh/uv:python3.14-bookwormghcr.io/astral-sh/uv:python3.13-bookwormghcr.io/astral-sh/uv:python3.12-bookwormghcr.io/astral-sh/uv:python3.11-bookwormghcr.io/astral-sh/uv:python3.10-bookwormghcr.io/astral-sh/uv:python3.9-bookwormghcr.io/astral-sh/uv:python3.8-bookworm
- Based on
python3.x-slim-bookworm: ghcr.io/astral-sh/uv:python3.14-bookworm-slimghcr.io/astral-sh/uv:python3.13-bookworm-slimghcr.io/astral-sh/uv:python3.12-bookworm-slimghcr.io/astral-sh/uv:python3.11-bookworm-slimghcr.io/astral-sh/uv:python3.10-bookworm-slimghcr.io/astral-sh/uv:python3.9-bookworm-slimghcr.io/astral-sh/uv:python3.8-bookworm-slim
As with the distroless image, each derived image is published with uv version tags as ghcr.io/astral-sh/uv:{major}.{minor}.{patch}-{base} and ghcr.io/astral-sh/uv:{major}.{minor}-{base}, e.g., ghcr.io/astral-sh/uv:0.9.8-alpine.
In addition, starting with 0.8 each derived image also sets UV_TOOL_BIN_DIR to /usr/local/bin to allow uv tool install to work as expected with the default user.
For more details, see the GitHub Container page.
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#installing-uv","level":3,"title":"Installing uv","text":"Use one of the above images with uv pre-installed or install uv by copying the binary from the official distroless Docker image:
DockerfileFROM python:3.12-slim-trixie\nCOPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/\n
Or, with the installer:
DockerfileFROM python:3.12-slim-trixie\n\n# The installer requires curl (and certificates) to download the release archive\nRUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates\n\n# Download the latest installer\nADD https://astral.sh/uv/install.sh /uv-installer.sh\n\n# Run the installer then remove it\nRUN sh /uv-installer.sh && rm /uv-installer.sh\n\n# Ensure the installed binary is on the `PATH`\nENV PATH=\"/root/.local/bin/:$PATH\"\n
Note this requires curl to be available.
In either case, it is best practice to pin to a specific uv version, e.g., with:
COPY --from=ghcr.io/astral-sh/uv:0.9.8 /uv /uvx /bin/\n
Tip
While the Dockerfile example above pins to a specific tag, it's also possible to pin a specific SHA256. Pinning a specific SHA256 is considered best practice in environments that require reproducible builds as tags can be moved across different commit SHAs.
# e.g., using a hash from a previous release\nCOPY --from=ghcr.io/astral-sh/uv@sha256:2381d6aa60c326b71fd40023f921a0a3b8f91b14d5db6b90402e65a635053709 /uv /uvx /bin/\n
Or, with the installer:
ADD https://astral.sh/uv/0.9.8/install.sh /uv-installer.sh\n
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#installing-a-project","level":3,"title":"Installing a project","text":"If you're using uv to manage your project, you can copy it into the image and install it:
Dockerfile# Copy the project into the image\nADD . /app\n\n# Sync the project into a new environment, asserting the lockfile is up to date\nWORKDIR /app\nRUN uv sync --locked\n
Important
It is best practice to add .venv to a .dockerignore file in your repository to prevent it from being included in image builds. The project virtual environment is dependent on your local platform and should be created from scratch in the image.
Then, to start your application by default:
Dockerfile# Presuming there is a `my_app` command provided by the project\nCMD [\"uv\", \"run\", \"my_app\"]\n
Tip
It is best practice to use intermediate layers separating installation of dependencies and the project itself to improve Docker image build times.
See a complete example in the uv-docker-example project.
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#using-the-environment","level":3,"title":"Using the environment","text":"Once the project is installed, you can either activate the project virtual environment by placing its binary directory at the front of the path:
DockerfileENV PATH=\"/app/.venv/bin:$PATH\"\n
Or, you can use uv run for any commands that require the environment:
DockerfileRUN uv run some_script.py\n
Tip
Alternatively, the UV_PROJECT_ENVIRONMENT setting can be set before syncing to install to the system Python environment and skip environment activation entirely.
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#using-installed-tools","level":3,"title":"Using installed tools","text":"To use installed tools, ensure the tool bin directory is on the path:
DockerfileENV PATH=/root/.local/bin:$PATH\nRUN uv tool install cowsay\n
$ docker run -it $(docker build -q .) /bin/bash -c \"cowsay -t hello\"\n _____\n| hello |\n =====\n \\\n \\\n ^__^\n (oo)\\_______\n (__)\\ )\\/\\\n ||----w |\n || ||\n
Note
The tool bin directory's location can be determined by running the uv tool dir --bin command in the container.
Alternatively, it can be set to a constant location:
DockerfileENV UV_TOOL_BIN_DIR=/opt/uv-bin/\n
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#installing-python-in-arm-musl-images","level":3,"title":"Installing Python in ARM musl images","text":"While uv will attempt to install a compatible Python version if no such version is available in the image, uv does not yet support installing Python for musl Linux on ARM. For example, if you are using an Alpine Linux base image on an ARM machine, you may need to add it with the system package manager:
apk add --no-cache python3~=3.12\n
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#developing-in-a-container","level":2,"title":"Developing in a container","text":"When developing, it's useful to mount the project directory into a container. With this setup, changes to the project can be immediately reflected in a containerized service without rebuilding the image. However, it is important not to include the project virtual environment (.venv) in the mount, because the virtual environment is platform specific and the one built for the image should be kept.
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#mounting-the-project-with-docker-run","level":3,"title":"Mounting the project with docker run","text":"Bind mount the project (in the working directory) to /app while retaining the .venv directory with an anonymous volume:
$ docker run --rm --volume .:/app --volume /app/.venv [...]\n
Tip
The --rm flag is included to ensure the container and anonymous volume are cleaned up when the container exits.
See a complete example in the uv-docker-example project.
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#configuring-watch-with-docker-compose","level":3,"title":"Configuring watch with docker compose","text":"When using Docker compose, more sophisticated tooling is available for container development. The watch option allows for greater granularity than is practical with a bind mount and supports triggering updates to the containerized service when files change.
Note
This feature requires Compose 2.22.0 which is bundled with Docker Desktop 4.24.
Configure watch in your Docker compose file to mount the project directory without syncing the project virtual environment and to rebuild the image when the configuration changes:
compose.yamlservices:\n example:\n build: .\n\n # ...\n\n develop:\n # Create a `watch` configuration to update the app\n #\n watch:\n # Sync the working directory with the `/app` directory in the container\n - action: sync\n path: .\n target: /app\n # Exclude the project virtual environment\n ignore:\n - .venv/\n\n # Rebuild the image on changes to the `pyproject.toml`\n - action: rebuild\n path: ./pyproject.toml\n
Then, run docker compose watch to run the container with the development setup.
See a complete example in the uv-docker-example project.
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#optimizations","level":2,"title":"Optimizations","text":"","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#compiling-bytecode","level":3,"title":"Compiling bytecode","text":"Compiling Python source files to bytecode is typically desirable for production images as it tends to improve startup time (at the cost of increased installation time).
To enable bytecode compilation, use the --compile-bytecode flag:
DockerfileRUN uv sync --compile-bytecode\n
Alternatively, you can set the UV_COMPILE_BYTECODE environment variable to ensure that all commands within the Dockerfile compile bytecode:
DockerfileENV UV_COMPILE_BYTECODE=1\n
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#caching","level":3,"title":"Caching","text":"A cache mount can be used to improve performance across builds:
DockerfileENV UV_LINK_MODE=copy\n\nRUN --mount=type=cache,target=/root/.cache/uv \\\n uv sync\n
Changing the default UV_LINK_MODE silences warnings about not being able to use hard links since the cache and sync target are on separate file systems.
If you're not mounting the cache, image size can be reduced by using the --no-cache flag or setting UV_NO_CACHE.
By default, managed Python installations are not cached before being installed. Setting UV_PYTHON_CACHE_DIR can be used in combination with a cache mount:
DockerfileENV UV_PYTHON_CACHE_DIR=/root/.cache/uv/python\n\nRUN --mount=type=cache,target=/root/.cache/uv \\\n uv python install\n
Note
The cache directory's location can be determined by running the uv cache dir command in the container.
Alternatively, the cache can be set to a constant location:
DockerfileENV UV_CACHE_DIR=/opt/uv-cache/\n
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#intermediate-layers","level":3,"title":"Intermediate layers","text":"If you're using uv to manage your project, you can improve build times by moving your transitive dependency installation into its own layer via the --no-install options.
uv sync --no-install-project will install the dependencies of the project but not the project itself. Since the project changes frequently, but its dependencies are generally static, this can be a big time saver.
Dockerfile# Install uv\nFROM python:3.12-slim\nCOPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/\n\n# Change the working directory to the `app` directory\nWORKDIR /app\n\n# Install dependencies\nRUN --mount=type=cache,target=/root/.cache/uv \\\n --mount=type=bind,source=uv.lock,target=uv.lock \\\n --mount=type=bind,source=pyproject.toml,target=pyproject.toml \\\n uv sync --locked --no-install-project\n\n# Copy the project into the image\nADD . /app\n\n# Sync the project\nRUN --mount=type=cache,target=/root/.cache/uv \\\n uv sync --locked\n
Note that the pyproject.toml is required to identify the project root and name, but the project contents are not copied into the image until the final uv sync command.
Tip
If you're using a workspace, then use the --no-install-workspace flag which excludes the project and any workspace members.
If you want to remove specific packages from the sync, use --no-install-package <name>.
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#non-editable-installs","level":3,"title":"Non-editable installs","text":"By default, uv installs projects and workspace members in editable mode, such that changes to the source code are immediately reflected in the environment.
uv sync and uv run both accept a --no-editable flag, which instructs uv to install the project in non-editable mode, removing any dependency on the source code.
In the context of a multi-stage Docker image, --no-editable can be used to include the project in the synced virtual environment from one stage, then copy the virtual environment alone (and not the source code) into the final image.
For example:
Dockerfile# Install uv\nFROM python:3.12-slim AS builder\nCOPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/\n\n# Change the working directory to the `app` directory\nWORKDIR /app\n\n# Install dependencies\nRUN --mount=type=cache,target=/root/.cache/uv \\\n --mount=type=bind,source=uv.lock,target=uv.lock \\\n --mount=type=bind,source=pyproject.toml,target=pyproject.toml \\\n uv sync --locked --no-install-project --no-editable\n\n# Copy the project into the intermediate image\nADD . /app\n\n# Sync the project\nRUN --mount=type=cache,target=/root/.cache/uv \\\n uv sync --locked --no-editable\n\nFROM python:3.12-slim\n\n# Copy the environment, but not the source code\nCOPY --from=builder --chown=app:app /app/.venv /app/.venv\n\n# Run the application\nCMD [\"/app/.venv/bin/hello\"]\n
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#using-uv-temporarily","level":3,"title":"Using uv temporarily","text":"If uv isn't needed in the final image, the binary can be mounted in each invocation:
DockerfileRUN --mount=from=ghcr.io/astral-sh/uv,source=/uv,target=/bin/uv \\\n uv sync\n
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#using-the-pip-interface","level":2,"title":"Using the pip interface","text":"","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#installing-a-package","level":3,"title":"Installing a package","text":"The system Python environment is safe to use this context, since a container is already isolated. The --system flag can be used to install in the system environment:
DockerfileRUN uv pip install --system ruff\n
To use the system Python environment by default, set the UV_SYSTEM_PYTHON variable:
DockerfileENV UV_SYSTEM_PYTHON=1\n
Alternatively, a virtual environment can be created and activated:
DockerfileRUN uv venv /opt/venv\n# Use the virtual environment automatically\nENV VIRTUAL_ENV=/opt/venv\n# Place entry points in the environment at the front of the path\nENV PATH=\"/opt/venv/bin:$PATH\"\n
When using a virtual environment, the --system flag should be omitted from uv invocations:
DockerfileRUN uv pip install ruff\n
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#installing-requirements","level":3,"title":"Installing requirements","text":"To install requirements files, copy them into the container:
DockerfileCOPY requirements.txt .\nRUN uv pip install -r requirements.txt\n
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#installing-a-project_1","level":3,"title":"Installing a project","text":"When installing a project alongside requirements, it is best practice to separate copying the requirements from the rest of the source code. This allows the dependencies of the project (which do not change often) to be cached separately from the project itself (which changes very frequently).
DockerfileCOPY pyproject.toml .\nRUN uv pip install -r pyproject.toml\nCOPY . .\nRUN uv pip install -e .\n
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/docker/#verifying-image-provenance","level":2,"title":"Verifying image provenance","text":"The Docker images are signed during the build process to provide proof of their origin. These attestations can be used to verify that an image was produced from an official channel.
For example, you can verify the attestations with the GitHub CLI tool gh:
$ gh attestation verify --owner astral-sh oci://ghcr.io/astral-sh/uv:latest\nLoaded digest sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx for oci://ghcr.io/astral-sh/uv:latest\nLoaded 1 attestation from GitHub API\n\nThe following policy criteria will be enforced:\n- OIDC Issuer must match:................... https://token.actions.githubusercontent.com\n- Source Repository Owner URI must match:... https://github.com/astral-sh\n- Predicate type must match:................ https://slsa.dev/provenance/v1\n- Subject Alternative Name must match regex: (?i)^https://github.com/astral-sh/\n\n✓ Verification succeeded!\n\nsha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx was attested by:\nREPO PREDICATE_TYPE WORKFLOW\nastral-sh/uv https://slsa.dev/provenance/v1 .github/workflows/build-docker.yml@refs/heads/main\n
This tells you that the specific Docker image was built by the official uv GitHub release workflow and hasn't been tampered with since.
GitHub attestations build on the sigstore.dev infrastructure. As such you can also use the cosign command to verify the attestation blob against the (multi-platform) manifest for uv:
$ REPO=astral-sh/uv\n$ gh attestation download --repo $REPO oci://ghcr.io/${REPO}:latest\nWrote attestations to file sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.jsonl.\nAny previous content has been overwritten\n\nThe trusted metadata is now available at sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.jsonl\n$ docker buildx imagetools inspect ghcr.io/${REPO}:latest --format \"{{json .Manifest}}\" > manifest.json\n$ cosign verify-blob-attestation \\\n --new-bundle-format \\\n --bundle \"$(jq -r .digest manifest.json).jsonl\" \\\n --certificate-oidc-issuer=\"https://token.actions.githubusercontent.com\" \\\n --certificate-identity-regexp=\"^https://github\\.com/${REPO}/.*\" \\\n <(jq -j '.|del(.digest,.size)' manifest.json)\nVerified OK\n
Tip
These examples use latest, but best practice is to verify the attestation for a specific version tag, e.g., ghcr.io/astral-sh/uv:0.9.8, or (even better) the specific image digest, such as ghcr.io/astral-sh/uv:0.5.27@sha256:5adf09a5a526f380237408032a9308000d14d5947eafa687ad6c6a2476787b4f.
","path":["Guides","Integrations","Using uv in Docker"],"tags":[]},{"location":"guides/integration/fastapi/","level":1,"title":"Using uv with FastAPI","text":"FastAPI is a modern, high-performance Python web framework. You can use uv to manage your FastAPI project, including installing dependencies, managing environments, running FastAPI applications, and more.
Note
You can view the source code for this guide in the uv-fastapi-example repository.
","path":["Guides","Integrations","Using uv with FastAPI"],"tags":[]},{"location":"guides/integration/fastapi/#migrating-an-existing-fastapi-project","level":2,"title":"Migrating an existing FastAPI project","text":"As an example, consider the sample application defined in the FastAPI documentation, structured as follows:
project\n└── app\n ├── __init__.py\n ├── main.py\n ├── dependencies.py\n ├── routers\n │ ├── __init__.py\n │ ├── items.py\n │ └── users.py\n └── internal\n ├── __init__.py\n └── admin.py\n
To use uv with this application, inside the project directory run:
$ uv init --app\n
This creates a project with an application layout and a pyproject.toml file.
Then, add a dependency on FastAPI:
$ uv add fastapi --extra standard\n
You should now have the following structure:
project\n├── pyproject.toml\n└── app\n ├── __init__.py\n ├── main.py\n ├── dependencies.py\n ├── routers\n │ ├── __init__.py\n │ ├── items.py\n │ └── users.py\n └── internal\n ├── __init__.py\n └── admin.py\n
And the contents of the pyproject.toml file should look something like this:
pyproject.toml[project]\nname = \"uv-fastapi-example\"\nversion = \"0.1.0\"\ndescription = \"FastAPI project\"\nreadme = \"README.md\"\nrequires-python = \">=3.12\"\ndependencies = [\n \"fastapi[standard]\",\n]\n
From there, you can run the FastAPI application with:
$ uv run fastapi dev\n
uv run will automatically resolve and lock the project dependencies (i.e., create a uv.lock alongside the pyproject.toml), create a virtual environment, and run the command in that environment.
Test the app by opening http://127.0.0.1:8000/?token=jessica in a web browser.
","path":["Guides","Integrations","Using uv with FastAPI"],"tags":[]},{"location":"guides/integration/fastapi/#deployment","level":2,"title":"Deployment","text":"To deploy the FastAPI application with Docker, you can use the following Dockerfile:
DockerfileFROM python:3.12-slim\n\n# Install uv.\nCOPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/\n\n# Copy the application into the container.\nCOPY . /app\n\n# Install the application dependencies.\nWORKDIR /app\nRUN uv sync --frozen --no-cache\n\n# Run the application.\nCMD [\"/app/.venv/bin/fastapi\", \"run\", \"app/main.py\", \"--port\", \"80\", \"--host\", \"0.0.0.0\"]\n
Build the Docker image with:
$ docker build -t fastapi-app .\n
Run the Docker container locally with:
$ docker run -p 8000:80 fastapi-app\n
Navigate to http://127.0.0.1:8000/?token=jessica in your browser to verify that the app is running correctly.
Tip
For more on using uv with Docker, see the Docker guide.
","path":["Guides","Integrations","Using uv with FastAPI"],"tags":[]},{"location":"guides/integration/github/","level":1,"title":"Using uv in GitHub Actions","text":"","path":["Guides","Integrations","Using uv in GitHub Actions"],"tags":[]},{"location":"guides/integration/github/#installation","level":2,"title":"Installation","text":"For use with GitHub Actions, we recommend the official astral-sh/setup-uv action, which installs uv, adds it to PATH, (optionally) persists the cache, and more, with support for all uv-supported platforms.
To install the latest version of uv:
example.ymlname: Example\n\njobs:\n uv-example:\n name: python\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v5\n\n - name: Install uv\n uses: astral-sh/setup-uv@v6\n
It is considered best practice to pin to a specific uv version, e.g., with:
example.ymlname: Example\n\njobs:\n uv-example:\n name: python\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v5\n\n - name: Install uv\n uses: astral-sh/setup-uv@v6\n with:\n # Install a specific version of uv.\n version: \"0.9.8\"\n
","path":["Guides","Integrations","Using uv in GitHub Actions"],"tags":[]},{"location":"guides/integration/github/#setting-up-python","level":2,"title":"Setting up Python","text":"Python can be installed with the python install command:
example.ymlname: Example\n\njobs:\n uv-example:\n name: python\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v5\n\n - name: Install uv\n uses: astral-sh/setup-uv@v6\n\n - name: Set up Python\n run: uv python install\n
This will respect the Python version pinned in the project.
Alternatively, the official GitHub setup-python action can be used. This can be faster, because GitHub caches the Python versions alongside the runner.
Set the python-version-file option to use the pinned version for the project:
example.ymlname: Example\n\njobs:\n uv-example:\n name: python\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v5\n\n - name: \"Set up Python\"\n uses: actions/setup-python@v6\n with:\n python-version-file: \".python-version\"\n\n - name: Install uv\n uses: astral-sh/setup-uv@v6\n
Or, specify the pyproject.toml file to ignore the pin and use the latest version compatible with the project's requires-python constraint:
example.ymlname: Example\n\njobs:\n uv-example:\n name: python\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v5\n\n - name: \"Set up Python\"\n uses: actions/setup-python@v6\n with:\n python-version-file: \"pyproject.toml\"\n\n - name: Install uv\n uses: astral-sh/setup-uv@v6\n
","path":["Guides","Integrations","Using uv in GitHub Actions"],"tags":[]},{"location":"guides/integration/github/#multiple-python-versions","level":2,"title":"Multiple Python versions","text":"When using a matrix to test multiple Python versions, set the Python version using astral-sh/setup-uv, which will override the Python version specification in the pyproject.toml or .python-version files:
example.ymljobs:\n build:\n name: continuous-integration\n runs-on: ubuntu-latest\n strategy:\n matrix:\n python-version:\n - \"3.10\"\n - \"3.11\"\n - \"3.12\"\n\n steps:\n - uses: actions/checkout@v5\n\n - name: Install uv and set the Python version\n uses: astral-sh/setup-uv@v6\n with:\n python-version: ${{ matrix.python-version }}\n
If not using the setup-uv action, you can set the UV_PYTHON environment variable:
example.ymljobs:\n build:\n name: continuous-integration\n runs-on: ubuntu-latest\n strategy:\n matrix:\n python-version:\n - \"3.10\"\n - \"3.11\"\n - \"3.12\"\n env:\n UV_PYTHON: ${{ matrix.python-version }}\n steps:\n - uses: actions/checkout@v5\n
","path":["Guides","Integrations","Using uv in GitHub Actions"],"tags":[]},{"location":"guides/integration/github/#syncing-and-running","level":2,"title":"Syncing and running","text":"Once uv and Python are installed, the project can be installed with uv sync and commands can be run in the environment with uv run:
example.ymlname: Example\n\njobs:\n uv-example:\n name: python\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v5\n\n - name: Install uv\n uses: astral-sh/setup-uv@v6\n\n - name: Install the project\n run: uv sync --locked --all-extras --dev\n\n - name: Run tests\n # For example, using `pytest`\n run: uv run pytest tests\n
Tip
The UV_PROJECT_ENVIRONMENT setting can be used to install to the system Python environment instead of creating a virtual environment.
","path":["Guides","Integrations","Using uv in GitHub Actions"],"tags":[]},{"location":"guides/integration/github/#caching","level":2,"title":"Caching","text":"It may improve CI times to store uv's cache across workflow runs.
The astral-sh/setup-uv has built-in support for persisting the cache:
example.yml- name: Enable caching\n uses: astral-sh/setup-uv@v6\n with:\n enable-cache: true\n
Alternatively, you can manage the cache manually with the actions/cache action:
example.ymljobs:\n install_job:\n env:\n # Configure a constant location for the uv cache\n UV_CACHE_DIR: /tmp/.uv-cache\n\n steps:\n # ... setup up Python and uv ...\n\n - name: Restore uv cache\n uses: actions/cache@v4\n with:\n path: /tmp/.uv-cache\n key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}\n restore-keys: |\n uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}\n uv-${{ runner.os }}\n\n # ... install packages, run tests, etc ...\n\n - name: Minimize uv cache\n run: uv cache prune --ci\n
The uv cache prune --ci command is used to reduce the size of the cache and is optimized for CI. Its effect on performance is dependent on the packages being installed.
Tip
If using uv pip, use requirements.txt instead of uv.lock in the cache key.
Note
When using non-ephemeral, self-hosted runners the default cache directory can grow unbounded. In this case, it may not be optimal to share the cache between jobs. Instead, move the cache inside the GitHub Workspace and remove it once the job finishes using a Post Job Hook.
install_job:\n env:\n # Configure a relative location for the uv cache\n UV_CACHE_DIR: ${{ github.workspace }}/.cache/uv\n
Using a post job hook requires setting the ACTIONS_RUNNER_HOOK_JOB_STARTED environment variable on the self-hosted runner to the path of a cleanup script such as the one shown below.
clean-uv-cache.sh#!/usr/bin/env sh\nuv cache clean\n
","path":["Guides","Integrations","Using uv in GitHub Actions"],"tags":[]},{"location":"guides/integration/github/#using-uv-pip","level":2,"title":"Using uv pip","text":"If using the uv pip interface instead of the uv project interface, uv requires a virtual environment by default. To allow installing packages into the system environment, use the --system flag on all uv invocations or set the UV_SYSTEM_PYTHON variable.
The UV_SYSTEM_PYTHON variable can be defined in at different scopes.
Opt-in for the entire workflow by defining it at the top level:
example.ymlenv:\n UV_SYSTEM_PYTHON: 1\n\njobs: ...\n
Or, opt-in for a specific job in the workflow:
example.ymljobs:\n install_job:\n env:\n UV_SYSTEM_PYTHON: 1\n ...\n
Or, opt-in for a specific step in a job:
example.ymlsteps:\n - name: Install requirements\n run: uv pip install -r requirements.txt\n env:\n UV_SYSTEM_PYTHON: 1\n
To opt-out again, the --no-system flag can be used in any uv invocation.
","path":["Guides","Integrations","Using uv in GitHub Actions"],"tags":[]},{"location":"guides/integration/github/#private-repos","level":2,"title":"Private repos","text":"If your project has dependencies on private GitHub repositories, you will need to configure a personal access token (PAT) to allow uv to fetch them.
After creating a PAT that has read access to the private repositories, add it as a repository secret.
Then, you can use the gh CLI (which is installed in GitHub Actions runners by default) to configure a credential helper for Git to use the PAT for queries to repositories hosted on github.com.
For example, if you called your repository secret MY_PAT:
example.ymlsteps:\n - name: Register the personal access token\n run: echo \"${{ secrets.MY_PAT }}\" | gh auth login --with-token\n - name: Configure the Git credential helper\n run: gh auth setup-git\n
","path":["Guides","Integrations","Using uv in GitHub Actions"],"tags":[]},{"location":"guides/integration/github/#publishing-to-pypi","level":2,"title":"Publishing to PyPI","text":"uv can be used to build and publish your package to PyPI from GitHub Actions. We provide a standalone example alongside this guide in astral-sh/trusted-publishing-examples. The workflow uses trusted publishing, so no credentials need to be configured.
In the example workflow, we use a script to test that the source distribution and the wheel are both functional and we didn't miss any files. This step is recommended, but optional.
First, add a release workflow to your project:
.github/workflows/publish.ymlname: \"Publish\"\n\non:\n push:\n tags:\n # Publish on any tag starting with a `v`, e.g., v0.1.0\n - v*\n\njobs:\n run:\n runs-on: ubuntu-latest\n environment:\n name: pypi\n permissions:\n id-token: write\n contents: read\n steps:\n - name: Checkout\n uses: actions/checkout@v5\n - name: Install uv\n uses: astral-sh/setup-uv@v6\n - name: Install Python 3.13\n run: uv python install 3.13\n - name: Build\n run: uv build\n # Check that basic features work and we didn't miss to include crucial files\n - name: Smoke test (wheel)\n run: uv run --isolated --no-project --with dist/*.whl tests/smoke_test.py\n - name: Smoke test (source distribution)\n run: uv run --isolated --no-project --with dist/*.tar.gz tests/smoke_test.py\n - name: Publish\n run: uv publish\n
Then, create the environment defined in the workflow in the GitHub repository under \"Settings\" -> \"Environments\".
Add a trusted publisher to your PyPI project in the project settings under \"Publishing\". Ensure that all fields match with your GitHub configuration.
After saving:
Finally, tag a release and push it. Make sure it starts with v to match the pattern in the workflow.
$ git tag -a v0.1.0 -m v0.1.0\n$ git push --tags\n
","path":["Guides","Integrations","Using uv in GitHub Actions"],"tags":[]},{"location":"guides/integration/gitlab/","level":1,"title":"Using uv in GitLab CI/CD","text":"","path":["Guides","Integrations","Using uv in GitLab CI/CD"],"tags":[]},{"location":"guides/integration/gitlab/#using-the-uv-image","level":2,"title":"Using the uv image","text":"Astral provides Docker images with uv preinstalled. Select a variant that is suitable for your workflow.
gitlab-ci.ymlvariables:\n UV_VERSION: \"0.5\"\n PYTHON_VERSION: \"3.12\"\n BASE_LAYER: bookworm-slim\n # GitLab CI creates a separate mountpoint for the build directory,\n # so we need to copy instead of using hard links.\n UV_LINK_MODE: copy\n\nuv:\n image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER\n script:\n # your `uv` commands\n
Note
If you are using a distroless image, you have to specify the entrypoint:
uv:\n image:\n name: ghcr.io/astral-sh/uv:$UV_VERSION\n entrypoint: [\"\"]\n # ...\n
","path":["Guides","Integrations","Using uv in GitLab CI/CD"],"tags":[]},{"location":"guides/integration/gitlab/#caching","level":2,"title":"Caching","text":"Persisting the uv cache between workflow runs can improve performance.
uv-install:\n variables:\n UV_CACHE_DIR: .uv-cache\n cache:\n - key:\n files:\n - uv.lock\n paths:\n - $UV_CACHE_DIR\n script:\n # Your `uv` commands\n - uv cache prune --ci\n
See the GitLab caching documentation for more details on configuring caching.
Using uv cache prune --ci at the end of the job is recommended to reduce cache size. See the uv cache documentation for more details.
","path":["Guides","Integrations","Using uv in GitLab CI/CD"],"tags":[]},{"location":"guides/integration/gitlab/#using-uv-pip","level":2,"title":"Using uv pip","text":"If using the uv pip interface instead of the uv project interface, uv requires a virtual environment by default. To allow installing packages into the system environment, use the --system flag on all uv invocations or set the UV_SYSTEM_PYTHON variable.
The UV_SYSTEM_PYTHON variable can be defined in at different scopes. You can read more about how variables and their precedence works in GitLab here
Opt-in for the entire workflow by defining it at the top level:
gitlab-ci.ymlvariables:\n UV_SYSTEM_PYTHON: 1\n\n# [...]\n
To opt-out again, the --no-system flag can be used in any uv invocation.
When persisting the cache, you may want to use requirements.txt or pyproject.toml as your cache key files instead of uv.lock.
","path":["Guides","Integrations","Using uv in GitLab CI/CD"],"tags":[]},{"location":"guides/integration/jupyter/","level":1,"title":"Using uv with Jupyter","text":"The Jupyter notebook is a popular tool for interactive computing, data analysis, and visualization. You can use Jupyter with uv in a few different ways, either to interact with a project, or as a standalone tool.
","path":["Guides","Integrations","Using uv with Jupyter"],"tags":[]},{"location":"guides/integration/jupyter/#using-jupyter-within-a-project","level":2,"title":"Using Jupyter within a project","text":"If you're working within a project, you can start a Jupyter server with access to the project's virtual environment via the following:
$ uv run --with jupyter jupyter lab\n
By default, jupyter lab will start the server at http://localhost:8888/lab.
Within a notebook, you can import your project's modules as you would in any other file in the project. For example, if your project depends on requests, import requests will import requests from the project's virtual environment.
If you're looking for read-only access to the project's virtual environment, then there's nothing more to it. However, if you need to install additional packages from within the notebook, there are a few extra details to consider.
","path":["Guides","Integrations","Using uv with Jupyter"],"tags":[]},{"location":"guides/integration/jupyter/#creating-a-kernel","level":3,"title":"Creating a kernel","text":"If you need to install packages from within the notebook, we recommend creating a dedicated kernel for your project. Kernels enable the Jupyter server to run in one environment, with individual notebooks running in their own, separate environments.
In the context of uv, we can create a kernel for a project while installing Jupyter itself in an isolated environment, as in uv run --with jupyter jupyter lab. Creating a kernel for the project ensures that the notebook is hooked up to the correct environment, and that any packages installed from within the notebook are installed into the project's virtual environment.
To create a kernel, you'll need to install ipykernel as a development dependency:
$ uv add --dev ipykernel\n
Then, you can create the kernel for project with:
$ uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=project\n
From there, start the server with:
$ uv run --with jupyter jupyter lab\n
When creating a notebook, select the project kernel from the dropdown. Then use !uv add pydantic to add pydantic to the project's dependencies, or !uv pip install pydantic to install pydantic into the project's virtual environment without persisting the change to the project pyproject.toml or uv.lock files. Either command will make import pydantic work within the notebook.
","path":["Guides","Integrations","Using uv with Jupyter"],"tags":[]},{"location":"guides/integration/jupyter/#installing-packages-without-a-kernel","level":3,"title":"Installing packages without a kernel","text":"If you don't want to create a kernel, you can still install packages from within the notebook. However, there are a few caveats to consider.
Though uv run --with jupyter runs in an isolated environment, within the notebook itself, !uv add and related commands will modify the project's environment, even without a kernel.
For example, running !uv add pydantic from within a notebook will add pydantic to the project's dependencies and virtual environment, such that import pydantic will work immediately, without further configuration or a server restart.
However, since the Jupyter server is the \"active\" environment, !uv pip install will install package's into Jupyter's environment, not the project environment. Such dependencies will persist for the lifetime of the Jupyter server, but may disappear on subsequent jupyter invocations.
If you're working with a notebook that relies on pip (e.g., via the %pip magic), you can include pip in your project's virtual environment by running uv venv --seed prior to starting the Jupyter server. For example, given:
$ uv venv --seed\n$ uv run --with jupyter jupyter lab\n
Subsequent %pip install invocations within the notebook will install packages into the project's virtual environment. However, such modifications will not be reflected in the project's pyproject.toml or uv.lock files.
","path":["Guides","Integrations","Using uv with Jupyter"],"tags":[]},{"location":"guides/integration/jupyter/#using-jupyter-as-a-standalone-tool","level":2,"title":"Using Jupyter as a standalone tool","text":"If you ever need ad hoc access to a notebook (i.e., to run a Python snippet interactively), you can start a Jupyter server at any time with uv tool run jupyter lab. This will run a Jupyter server in an isolated environment.
","path":["Guides","Integrations","Using uv with Jupyter"],"tags":[]},{"location":"guides/integration/jupyter/#using-jupyter-with-a-non-project-environment","level":2,"title":"Using Jupyter with a non-project environment","text":"If you need to run Jupyter in a virtual environment that isn't associated with a project (e.g., has no pyproject.toml or uv.lock), you can do so by adding Jupyter to the environment directly. For example:
macOS and LinuxWindows $ uv venv --seed\n$ uv pip install pydantic\n$ uv pip install jupyterlab\n$ .venv/bin/jupyter lab\n
PS> uv venv --seed\nPS> uv pip install pydantic\nPS> uv pip install jupyterlab\nPS> .venv\\Scripts\\jupyter lab\n
From here, import pydantic will work within the notebook, and you can install additional packages via !uv pip install, or even !pip install.
","path":["Guides","Integrations","Using uv with Jupyter"],"tags":[]},{"location":"guides/integration/jupyter/#using-jupyter-from-vs-code","level":2,"title":"Using Jupyter from VS Code","text":"You can also engage with Jupyter notebooks from within an editor like VS Code. To connect a uv-managed project to a Jupyter notebook within VS Code, we recommend creating a kernel for the project, as in the following:
# Create a project.\n$ uv init project\n\n# Move into the project directory.\n$ cd project\n\n# Add ipykernel as a dev dependency.\n$ uv add --dev ipykernel\n\n# Open the project in VS Code.\n$ code .\n
Once the project directory is open in VS Code, you can create a new Jupyter notebook by selecting \"Create: New Jupyter Notebook\" from the command palette. When prompted to select a kernel, choose \"Python Environments\" and select the virtual environment you created earlier (e.g., .venv/bin/python on macOS and Linux, or .venv\\Scripts\\python on Windows).
Note
VS Code requires ipykernel to be present in the project environment. If you'd prefer to avoid adding ipykernel as a dev dependency, you can install it directly into the project environment with uv pip install ipykernel.
If you need to manipulate the project's environment from within the notebook, you may need to add uv as an explicit development dependency:
$ uv add --dev uv\n
From there, you can use !uv add pydantic to add pydantic to the project's dependencies, or !uv pip install pydantic to install pydantic into the project's virtual environment without updating the project's pyproject.toml or uv.lock files.
","path":["Guides","Integrations","Using uv with Jupyter"],"tags":[]},{"location":"guides/integration/marimo/","level":1,"title":"Using uv with marimo","text":"marimo is an open-source Python notebook that blends interactive computing with the reproducibility and reusability of traditional software, letting you version with Git, run as scripts, and share as apps. Because marimo notebooks are stored as pure Python scripts, they are able to integrate tightly with uv.
You can readily use marimo as a standalone tool, as self-contained scripts, in projects, and in non-project environments.
","path":["Guides","Integrations","Using uv with marimo"],"tags":[]},{"location":"guides/integration/marimo/#using-marimo-as-a-standalone-tool","level":2,"title":"Using marimo as a standalone tool","text":"For ad-hoc access to marimo notebooks, start a marimo server at any time in an isolated environment with:
$ uvx marimo edit\n
Start a specific notebook with:
$ uvx marimo edit my_notebook.py\n
","path":["Guides","Integrations","Using uv with marimo"],"tags":[]},{"location":"guides/integration/marimo/#using-marimo-with-inline-script-metadata","level":2,"title":"Using marimo with inline script metadata","text":"Because marimo notebooks are stored as Python scripts, they can encapsulate their own dependencies using inline script metadata, via uv's support for scripts. For example, to add numpy as a dependency to your notebook, use this command:
$ uv add --script my_notebook.py numpy\n
To interactively edit a notebook containing inline script metadata, use:
$ uvx marimo edit --sandbox my_notebook.py\n
marimo will automatically use uv to start your notebook in an isolated virtual environment with your script's dependencies. Packages installed from the marimo UI will automatically be added to the notebook's script metadata.
You can optionally run these notebooks as Python scripts, without opening an interactive session:
$ uv run my_notebook.py\n
","path":["Guides","Integrations","Using uv with marimo"],"tags":[]},{"location":"guides/integration/marimo/#using-marimo-within-a-project","level":2,"title":"Using marimo within a project","text":"If you're working within a project, you can start a marimo notebook with access to the project's virtual environment via the following command (assuming marimo is a project dependency):
$ uv run marimo edit my_notebook.py\n
To make additional packages available to your notebook, either add them to your project with uv add, or use marimo's built-in package installation UI, which will invoke uv add on your behalf.
If marimo is not a project dependency, you can still run a notebook with the following command:
$ uv run --with marimo marimo edit my_notebook.py\n
This will let you import your project's modules while editing your notebook. However, packages installed via marimo's UI when running in this way will not be added to your project, and may disappear on subsequent marimo invocations.
","path":["Guides","Integrations","Using uv with marimo"],"tags":[]},{"location":"guides/integration/marimo/#using-marimo-in-a-non-project-environment","level":2,"title":"Using marimo in a non-project environment","text":"To run marimo in a virtual environment that isn't associated with a project, add marimo to the environment directly:
$ uv venv\n$ uv pip install numpy\n$ uv pip install marimo\n$ uv run marimo edit\n
From here, import numpy will work within the notebook, and marimo's UI installer will add packages to the environment with uv pip install on your behalf.
","path":["Guides","Integrations","Using uv with marimo"],"tags":[]},{"location":"guides/integration/marimo/#running-marimo-notebooks-as-scripts","level":2,"title":"Running marimo notebooks as scripts","text":"Regardless of how your dependencies are managed (with inline script metadata, within a project, or with a non-project environment), you can run marimo notebooks as scripts with:
$ uv run my_notebook.py\n
This executes your notebook as a Python script, without opening an interactive session in your browser.
","path":["Guides","Integrations","Using uv with marimo"],"tags":[]},{"location":"guides/integration/pre-commit/","level":1,"title":"Using uv in pre-commit","text":"An official pre-commit hook is provided at astral-sh/uv-pre-commit.
To use uv with pre-commit, add one of the following examples to the repos list in the .pre-commit-config.yaml.
To make sure your uv.lock file is up to date even if your pyproject.toml file was changed:
.pre-commit-config.yamlrepos:\n - repo: https://github.com/astral-sh/uv-pre-commit\n # uv version.\n rev: 0.9.8\n hooks:\n - id: uv-lock\n
To keep a requirements.txt file in sync with your uv.lock file:
.pre-commit-config.yamlrepos:\n - repo: https://github.com/astral-sh/uv-pre-commit\n # uv version.\n rev: 0.9.8\n hooks:\n - id: uv-export\n
To compile requirements files:
.pre-commit-config.yamlrepos:\n - repo: https://github.com/astral-sh/uv-pre-commit\n # uv version.\n rev: 0.9.8\n hooks:\n # Compile requirements\n - id: pip-compile\n args: [requirements.in, -o, requirements.txt]\n
To compile alternative requirements files, modify args and files:
.pre-commit-config.yamlrepos:\n - repo: https://github.com/astral-sh/uv-pre-commit\n # uv version.\n rev: 0.9.8\n hooks:\n # Compile requirements\n - id: pip-compile\n args: [requirements-dev.in, -o, requirements-dev.txt]\n files: ^requirements-dev\\.(in|txt)$\n
To run the hook over multiple files at the same time, add additional entries:
.pre-commit-config.yamlrepos:\n - repo: https://github.com/astral-sh/uv-pre-commit\n # uv version.\n rev: 0.9.8\n hooks:\n # Compile requirements\n - id: pip-compile\n name: pip-compile requirements.in\n args: [requirements.in, -o, requirements.txt]\n - id: pip-compile\n name: pip-compile requirements-dev.in\n args: [requirements-dev.in, -o, requirements-dev.txt]\n files: ^requirements-dev\\.(in|txt)$\n
","path":["Guides","Integrations","Using uv with pre-commit"],"tags":[]},{"location":"guides/integration/pytorch/","level":1,"title":"Using uv with PyTorch","text":"The PyTorch ecosystem is a popular choice for deep learning research and development. You can use uv to manage PyTorch projects and PyTorch dependencies across different Python versions and environments, even controlling for the choice of accelerator (e.g., CPU-only vs. CUDA).
Note
Some of the features outlined in this guide require uv version 0.5.3 or later. We recommend upgrading prior to configuring PyTorch.
","path":["Guides","Integrations","Using uv with PyTorch"],"tags":[]},{"location":"guides/integration/pytorch/#installing-pytorch","level":2,"title":"Installing PyTorch","text":"From a packaging perspective, PyTorch has a few uncommon characteristics:
- Many PyTorch wheels are hosted on a dedicated index, rather than the Python Package Index (PyPI). As such, installing PyTorch often requires configuring a project to use the PyTorch index.
- PyTorch produces distinct builds for each accelerator (e.g., CPU-only, CUDA). Since there's no standardized mechanism for specifying these accelerators when publishing or installing, PyTorch encodes them in the local version specifier. As such, PyTorch versions will often look like
2.5.1+cpu, 2.5.1+cu121, etc. - Builds for different accelerators are published to different indexes. For example, the
+cpu builds are published on https://download.pytorch.org/whl/cpu, while the +cu121 builds are published on https://download.pytorch.org/whl/cu121.
As such, the necessary packaging configuration will vary depending on both the platforms you need to support and the accelerators you want to enable.
To start, consider the following (default) configuration, which would be generated by running uv init --python 3.12 followed by uv add torch torchvision.
In this case, PyTorch would be installed from PyPI, which hosts CPU-only wheels for Windows and macOS, and GPU-accelerated wheels on Linux (targeting CUDA 12.6):
[project]\nname = \"project\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12\"\ndependencies = [\n \"torch>=2.7.0\",\n \"torchvision>=0.22.0\",\n]\n
Supported Python versions
At time of writing, PyTorch does not yet publish wheels for Python 3.14; as such projects with requires-python = \">=3.14\" may fail to resolve. See the compatibility matrix.
This is a valid configuration for projects that want to use CPU builds on Windows and macOS, and CUDA-enabled builds on Linux. However, if you need to support different platforms or accelerators, you'll need to configure the project accordingly.
","path":["Guides","Integrations","Using uv with PyTorch"],"tags":[]},{"location":"guides/integration/pytorch/#using-a-pytorch-index","level":2,"title":"Using a PyTorch index","text":"In some cases, you may want to use a specific PyTorch variant across all platforms. For example, you may want to use the CPU-only builds on Linux too.
In such cases, the first step is to add the relevant PyTorch index to your pyproject.toml:
CPU-onlyCUDA 11.8CUDA 12.6CUDA 12.8ROCm6Intel GPUs [[tool.uv.index]]\nname = \"pytorch-cpu\"\nurl = \"https://download.pytorch.org/whl/cpu\"\nexplicit = true\n
[[tool.uv.index]]\nname = \"pytorch-cu118\"\nurl = \"https://download.pytorch.org/whl/cu118\"\nexplicit = true\n
[[tool.uv.index]]\nname = \"pytorch-cu126\"\nurl = \"https://download.pytorch.org/whl/cu126\"\nexplicit = true\n
[[tool.uv.index]]\nname = \"pytorch-cu128\"\nurl = \"https://download.pytorch.org/whl/cu128\"\nexplicit = true\n
[[tool.uv.index]]\nname = \"pytorch-rocm\"\nurl = \"https://download.pytorch.org/whl/rocm6.3\"\nexplicit = true\n
[[tool.uv.index]]\nname = \"pytorch-xpu\"\nurl = \"https://download.pytorch.org/whl/xpu\"\nexplicit = true\n
We recommend the use of explicit = true to ensure that the index is only used for torch, torchvision, and other PyTorch-related packages, as opposed to generic dependencies like jinja2, which should continue to be sourced from the default index (PyPI).
Next, update the pyproject.toml to point torch and torchvision to the desired index:
CPU-onlyCUDA 11.8CUDA 12.6CUDA 12.8ROCm6Intel GPUs [tool.uv.sources]\ntorch = [\n { index = \"pytorch-cpu\" },\n]\ntorchvision = [\n { index = \"pytorch-cpu\" },\n]\n
PyTorch doesn't publish CUDA builds for macOS. As such, we gate on sys_platform to instruct uv to use the PyTorch index on Linux and Windows, but fall back to PyPI on macOS:
[tool.uv.sources]\ntorch = [\n { index = \"pytorch-cu118\", marker = \"sys_platform == 'linux' or sys_platform == 'win32'\" },\n]\ntorchvision = [\n { index = \"pytorch-cu118\", marker = \"sys_platform == 'linux' or sys_platform == 'win32'\" },\n]\n
PyTorch doesn't publish CUDA builds for macOS. As such, we gate on sys_platform to instruct uv to limit the PyTorch index to Linux and Windows, falling back to PyPI on macOS:
[tool.uv.sources]\ntorch = [\n { index = \"pytorch-cu126\", marker = \"sys_platform == 'linux' or sys_platform == 'win32'\" },\n]\ntorchvision = [\n { index = \"pytorch-cu126\", marker = \"sys_platform == 'linux' or sys_platform == 'win32'\" },\n]\n
PyTorch doesn't publish CUDA builds for macOS. As such, we gate on sys_platform to instruct uv to limit the PyTorch index to Linux and Windows, falling back to PyPI on macOS:
[tool.uv.sources]\ntorch = [\n { index = \"pytorch-cu128\", marker = \"sys_platform == 'linux' or sys_platform == 'win32'\" },\n]\ntorchvision = [\n { index = \"pytorch-cu128\", marker = \"sys_platform == 'linux' or sys_platform == 'win32'\" },\n]\n
PyTorch doesn't publish ROCm6 builds for macOS or Windows. As such, we gate on sys_platform to instruct uv to limit the PyTorch index to Linux, falling back to PyPI on macOS and Windows:
[tool.uv.sources]\ntorch = [\n { index = \"pytorch-rocm\", marker = \"sys_platform == 'linux'\" },\n]\ntorchvision = [\n { index = \"pytorch-rocm\", marker = \"sys_platform == 'linux'\" },\n]\n# ROCm6 support relies on `pytorch-triton-rocm`, which should also be installed from the PyTorch index\n# (and included in `project.dependencies`).\npytorch-triton-rocm = [\n { index = \"pytorch-rocm\", marker = \"sys_platform == 'linux'\" },\n]\n
PyTorch doesn't publish Intel GPU builds for macOS. As such, we gate on sys_platform to instruct uv to limit the PyTorch index to Linux and Windows, falling back to PyPI on macOS:
[tool.uv.sources]\ntorch = [\n { index = \"pytorch-xpu\", marker = \"sys_platform == 'linux' or sys_platform == 'win32'\" },\n]\ntorchvision = [\n { index = \"pytorch-xpu\", marker = \"sys_platform == 'linux' or sys_platform == 'win32'\" },\n]\n# Intel GPU support relies on `pytorch-triton-xpu`, which should also be installed from the PyTorch index\n# (and included in `project.dependencies`).\npytorch-triton-xpu = [\n { index = \"pytorch-xpu\", marker = \"sys_platform == 'linux' or sys_platform == 'win32'\" },\n]\n
As a complete example, the following project would use PyTorch's CPU-only builds on all platforms:
[project]\nname = \"project\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12.0\"\ndependencies = [\n \"torch>=2.7.0\",\n \"torchvision>=0.22.0\",\n]\n\n[tool.uv.sources]\ntorch = [\n { index = \"pytorch-cpu\" },\n]\ntorchvision = [\n { index = \"pytorch-cpu\" },\n]\n\n[[tool.uv.index]]\nname = \"pytorch-cpu\"\nurl = \"https://download.pytorch.org/whl/cpu\"\nexplicit = true\n
","path":["Guides","Integrations","Using uv with PyTorch"],"tags":[]},{"location":"guides/integration/pytorch/#configuring-accelerators-with-environment-markers","level":2,"title":"Configuring accelerators with environment markers","text":"In some cases, you may want to use CPU-only builds in one environment (e.g., macOS and Windows), and CUDA-enabled builds in another (e.g., Linux).
With tool.uv.sources, you can use environment markers to specify the desired index for each platform. For example, the following configuration would use PyTorch's CUDA-enabled builds on Linux, and CPU-only builds on all other platforms (e.g., macOS and Windows):
[project]\nname = \"project\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12.0\"\ndependencies = [\n \"torch>=2.7.0\",\n \"torchvision>=0.22.0\",\n]\n\n[tool.uv.sources]\ntorch = [\n { index = \"pytorch-cpu\", marker = \"sys_platform != 'linux'\" },\n { index = \"pytorch-cu128\", marker = \"sys_platform == 'linux'\" },\n]\ntorchvision = [\n { index = \"pytorch-cpu\", marker = \"sys_platform != 'linux'\" },\n { index = \"pytorch-cu128\", marker = \"sys_platform == 'linux'\" },\n]\n\n[[tool.uv.index]]\nname = \"pytorch-cpu\"\nurl = \"https://download.pytorch.org/whl/cpu\"\nexplicit = true\n\n[[tool.uv.index]]\nname = \"pytorch-cu128\"\nurl = \"https://download.pytorch.org/whl/cu128\"\nexplicit = true\n
Similarly, the following configuration would use PyTorch's AMD GPU builds on Linux, and CPU-only builds on Windows and macOS (by way of falling back to PyPI):
[project]\nname = \"project\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12.0\"\ndependencies = [\n \"torch>=2.7.0\",\n \"torchvision>=0.22.0\",\n \"pytorch-triton-rocm>=3.3.0 ; sys_platform == 'linux'\",\n]\n\n[tool.uv.sources]\ntorch = [\n { index = \"pytorch-rocm\", marker = \"sys_platform == 'linux'\" },\n]\ntorchvision = [\n { index = \"pytorch-rocm\", marker = \"sys_platform == 'linux'\" },\n]\npytorch-triton-rocm = [\n { index = \"pytorch-rocm\", marker = \"sys_platform == 'linux'\" },\n]\n\n[[tool.uv.index]]\nname = \"pytorch-rocm\"\nurl = \"https://download.pytorch.org/whl/rocm6.3\"\nexplicit = true\n
Or, for Intel GPU builds:
[project]\nname = \"project\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12.0\"\ndependencies = [\n \"torch>=2.7.0\",\n \"torchvision>=0.22.0\",\n \"pytorch-triton-xpu>=3.3.0 ; sys_platform == 'win32' or sys_platform == 'linux'\",\n]\n\n[tool.uv.sources]\ntorch = [\n { index = \"pytorch-xpu\", marker = \"sys_platform == 'win32' or sys_platform == 'linux'\" },\n]\ntorchvision = [\n { index = \"pytorch-xpu\", marker = \"sys_platform == 'win32' or sys_platform == 'linux'\" },\n]\npytorch-triton-xpu = [\n { index = \"pytorch-xpu\", marker = \"sys_platform == 'win32' or sys_platform == 'linux'\" },\n]\n\n[[tool.uv.index]]\nname = \"pytorch-xpu\"\nurl = \"https://download.pytorch.org/whl/xpu\"\nexplicit = true\n
","path":["Guides","Integrations","Using uv with PyTorch"],"tags":[]},{"location":"guides/integration/pytorch/#configuring-accelerators-with-optional-dependencies","level":2,"title":"Configuring accelerators with optional dependencies","text":"In some cases, you may want to use CPU-only builds in some cases, but CUDA-enabled builds in others, with the choice toggled by a user-provided extra (e.g., uv sync --extra cpu vs. uv sync --extra cu128).
With tool.uv.sources, you can use extra markers to specify the desired index for each enabled extra. For example, the following configuration would use PyTorch's CPU-only for uv sync --extra cpu and CUDA-enabled builds for uv sync --extra cu128:
[project]\nname = \"project\"\nversion = \"0.1.0\"\nrequires-python = \">=3.12.0\"\ndependencies = []\n\n[project.optional-dependencies]\ncpu = [\n \"torch>=2.7.0\",\n \"torchvision>=0.22.0\",\n]\ncu128 = [\n \"torch>=2.7.0\",\n \"torchvision>=0.22.0\",\n]\n\n[tool.uv]\nconflicts = [\n [\n { extra = \"cpu\" },\n { extra = \"cu128\" },\n ],\n]\n\n[tool.uv.sources]\ntorch = [\n { index = \"pytorch-cpu\", extra = \"cpu\" },\n { index = \"pytorch-cu128\", extra = \"cu128\" },\n]\ntorchvision = [\n { index = \"pytorch-cpu\", extra = \"cpu\" },\n { index = \"pytorch-cu128\", extra = \"cu128\" },\n]\n\n[[tool.uv.index]]\nname = \"pytorch-cpu\"\nurl = \"https://download.pytorch.org/whl/cpu\"\nexplicit = true\n\n[[tool.uv.index]]\nname = \"pytorch-cu128\"\nurl = \"https://download.pytorch.org/whl/cu128\"\nexplicit = true\n
Note
Since GPU-accelerated builds aren't available on macOS, the above configuration will fail to install on macOS when the cu128 extra is enabled.
","path":["Guides","Integrations","Using uv with PyTorch"],"tags":[]},{"location":"guides/integration/pytorch/#the-uv-pip-interface","level":2,"title":"The uv pip interface","text":"While the above examples are focused on uv's project interface (uv lock, uv sync, uv run, etc.), PyTorch can also be installed via the uv pip interface.
PyTorch itself offers a dedicated interface to determine the appropriate pip command to run for a given target configuration. For example, you can install stable, CPU-only PyTorch on Linux with:
$ pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu\n
To use the same workflow with uv, replace pip3 with uv pip:
$ uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu\n
","path":["Guides","Integrations","Using uv with PyTorch"],"tags":[]},{"location":"guides/integration/pytorch/#automatic-backend-selection","level":2,"title":"Automatic backend selection","text":"uv supports automatic selection of the appropriate PyTorch index via the --torch-backend=auto command-line argument (or the UV_TORCH_BACKEND=auto environment variable), as in:
$ # With a command-line argument.\n$ uv pip install torch --torch-backend=auto\n\n$ # With an environment variable.\n$ UV_TORCH_BACKEND=auto uv pip install torch\n
When enabled, uv will query for the installed CUDA driver, AMD GPU versions, and Intel GPU presence, then use the most-compatible PyTorch index for all relevant packages (e.g., torch, torchvision, etc.). If no such GPU is found, uv will fall back to the CPU-only index. uv will continue to respect existing index configuration for any packages outside the PyTorch ecosystem.
You can also select a specific backend (e.g., CUDA 12.6) with --torch-backend=cu126 (or UV_TORCH_BACKEND=cu126):
$ # With a command-line argument.\n$ uv pip install torch torchvision --torch-backend=cu126\n\n$ # With an environment variable.\n$ UV_TORCH_BACKEND=cu126 uv pip install torch torchvision\n
At present, --torch-backend is only available in the uv pip interface.
","path":["Guides","Integrations","Using uv with PyTorch"],"tags":[]},{"location":"guides/migration/","level":1,"title":"Migration guides","text":"Learn how to migrate from other tools to uv:
- Migrate from pip to uv projects
Note
Other guides, such as migrating from another project management tool, or from pip to uv pip are not yet available. See #5200 to track progress.
Or, explore the integration guides to learn how to use uv with other software.
","path":["Guides","Migration","Migration guides"],"tags":[]},{"location":"guides/migration/pip-to-project/","level":1,"title":"Migrating from pip to a uv project","text":"This guide will discuss converting from a pip and pip-tools workflow centered on requirements files to uv's project workflow using a pyproject.toml and uv.lock file.
Note
If you're looking to migrate from pip and pip-tools to uv's drop-in interface or from an existing workflow where you're already using a pyproject.toml, those guides are not yet written. See #5200 to track progress.
We'll start with an overview of developing with pip, then discuss migrating to uv.
Tip
If you're familiar with the ecosystem, you can jump ahead to the requirements file import instructions.
","path":["Guides","Migration","Migrating from pip to a uv project"],"tags":[]},{"location":"guides/migration/pip-to-project/#understanding-pip-workflows","level":2,"title":"Understanding pip workflows","text":"","path":["Guides","Migration","Migrating from pip to a uv project"],"tags":[]},{"location":"guides/migration/pip-to-project/#project-dependencies","level":3,"title":"Project dependencies","text":"When you want to use a package in your project, you need to install it first. pip supports imperative installation of packages, e.g.:
$ pip install fastapi\n
This installs the package into the environment that pip is installed in. This may be a virtual environment, or, the global environment of your system's Python installation.
Then, you can run a Python script that requires the package:
example.pyimport fastapi\n
It's best practice to create a virtual environment for each project, to avoid mixing packages between them. For example:
$ python -m venv\n$ source .venv/bin/activate\n$ pip ...\n
We will revisit this topic in the project environments section below.
","path":["Guides","Migration","Migrating from pip to a uv project"],"tags":[]},{"location":"guides/migration/pip-to-project/#requirements-files","level":3,"title":"Requirements files","text":"When sharing projects with others, it's useful to declare all the packages you require upfront. pip supports installing requirements from a file, e.g.:
requirements.txtfastapi\n
$ pip install -r requirements.txt\n
Notice above that fastapi is not \"locked\" to a specific version — each person working on the project may have a different version of fastapi installed. pip-tools was created to improve this experience.
When using pip-tools, requirements files specify both the dependencies for your project and lock dependencies to a specific version — the file extension is used to differentiate between the two. For example, if you require fastapi and pydantic, you'd specify these in a requirements.in file:
requirements.infastapi\npydantic>2\n
Notice there's a version constraint on pydantic — this means only pydantic versions later than 2.0.0 can be used. In contrast, fastapi does not have a version constraint — any version can be used.
These dependencies can be compiled into a requirements.txt file:
$ pip-compile requirements.in -o requirements.txt\n
requirements.txtannotated-types==0.7.0\n # via pydantic\nanyio==4.8.0\n # via starlette\nfastapi==0.115.11\n # via -r requirements.in\nidna==3.10\n # via anyio\npydantic==2.10.6\n # via\n # -r requirements.in\n # fastapi\npydantic-core==2.27.2\n # via pydantic\nsniffio==1.3.1\n # via anyio\nstarlette==0.46.1\n # via fastapi\ntyping-extensions==4.12.2\n # via\n # fastapi\n # pydantic\n # pydantic-core\n
Here, all the versions constraints are exact. Only a single version of each package can be used. The above example was generated with uv pip compile, but could also be generated with pip-compile from pip-tools.
Though less common, the requirements.txt can also be generated using pip freeze, by first installing the input dependencies into the environment then exporting the installed versions:
$ pip install -r requirements.in\n$ pip freeze > requirements.txt\n
requirements.txtannotated-types==0.7.0\nanyio==4.8.0\nfastapi==0.115.11\nidna==3.10\npydantic==2.10.6\npydantic-core==2.27.2\nsniffio==1.3.1\nstarlette==0.46.1\ntyping-extensions==4.12.2\n
After compiling dependencies into a locked set of versions, these files are committed to version control and distributed with the project.
Then, when someone wants to use the project, they install from the requirements file:
$ pip install -r requirements.txt\n
","path":["Guides","Migration","Migrating from pip to a uv project"],"tags":[]},{"location":"guides/migration/pip-to-project/#development-dependencies","level":3,"title":"Development dependencies","text":"The requirements file format can only describe a single set of dependencies at once. This means if you have additional groups of dependencies, such as development dependencies, they need separate files. For example, we'll create a -dev dependency file:
requirements-dev.in-r requirements.in\n-c requirements.txt\n\npytest\n
Notice the base requirements are included with -r requirements.in. This ensures your development environment considers all of the dependencies together. The -c requirements.txt constrains the package version to ensure that the requirements-dev.txt uses the same versions as requirements.txt.
Note
It's common to use -r requirements.txt directly instead of using both -r requirements.in, and -c requirements.txt. There's no difference in the resulting package versions, but using both files produces annotations which allow you to determine which dependencies are direct (annotated with -r requirements.in) and which are indirect (only annotated with -c requirements.txt).
The compiled development dependencies look like:
requirements-dev.txtannotated-types==0.7.0\n # via\n # -c requirements.txt\n # pydantic\nanyio==4.8.0\n # via\n # -c requirements.txt\n # starlette\nfastapi==0.115.11\n # via\n # -c requirements.txt\n # -r requirements.in\nidna==3.10\n # via\n # -c requirements.txt\n # anyio\niniconfig==2.0.0\n # via pytest\npackaging==24.2\n # via pytest\npluggy==1.5.0\n # via pytest\npydantic==2.10.6\n # via\n # -c requirements.txt\n # -r requirements.in\n # fastapi\npydantic-core==2.27.2\n # via\n # -c requirements.txt\n # pydantic\npytest==8.3.5\n # via -r requirements-dev.in\nsniffio==1.3.1\n # via\n # -c requirements.txt\n # anyio\nstarlette==0.46.1\n # via\n # -c requirements.txt\n # fastapi\ntyping-extensions==4.12.2\n # via\n # -c requirements.txt\n # fastapi\n # pydantic\n # pydantic-core\n
As with the base dependency files, these are committed to version control and distributed with the project. When someone wants to work on the project, they'll install from the requirements file:
$ pip install -r requirements-dev.txt\n
","path":["Guides","Migration","Migrating from pip to a uv project"],"tags":[]},{"location":"guides/migration/pip-to-project/#platform-specific-dependencies","level":3,"title":"Platform-specific dependencies","text":"When compiling dependencies with pip or pip-tools, the result is only usable on the same platform as it is generated on. This poses a problem for projects which need to be usable on multiple platforms, such as Windows and macOS.
For example, take a simple dependency:
requirements.intqdm\n
On Linux, this compiles to:
requirements-linux.txttqdm==4.67.1\n # via -r requirements.in\n
While on Windows, this compiles to:
requirements-win.txtcolorama==0.4.6\n # via tqdm\ntqdm==4.67.1\n # via -r requirements.in\n
colorama is a Windows-only dependency of tqdm.
When using pip and pip-tools, a project needs to declare a requirements lock file for each supported platform.
Note
uv's resolver can compile dependencies for multiple platforms at once (see \"universal resolution\"), allowing you to use a single requirements.txt for all platforms:
$ uv pip compile --universal requirements.in\n
requirements.txtcolorama==0.4.6 ; sys_platform == 'win32'\n # via tqdm\ntqdm==4.67.1\n # via -r requirements.in\n
This resolution mode is also used when using a pyproject.toml and uv.lock.
","path":["Guides","Migration","Migrating from pip to a uv project"],"tags":[]},{"location":"guides/migration/pip-to-project/#migrating-to-a-uv-project","level":2,"title":"Migrating to a uv project","text":"","path":["Guides","Migration","Migrating from pip to a uv project"],"tags":[]},{"location":"guides/migration/pip-to-project/#the-pyprojecttoml","level":3,"title":"The pyproject.toml","text":"The pyproject.toml is a standardized file for Python project metadata. It replaces requirements.in files, allowing you to represent arbitrary groups of project dependencies. It also provides a centralized location for metadata about your project, such as the build system or tool settings.
For example, the requirements.in and requirements-dev.in files above can be translated to a pyproject.toml as follows:
pyproject.toml[project]\nname = \"example\"\nversion = \"0.0.1\"\ndependencies = [\n \"fastapi\",\n \"pydantic>2\"\n]\n\n[dependency-groups]\ndev = [\"pytest\"]\n
We'll discuss the commands necessary to automate these imports below.
","path":["Guides","Migration","Migrating from pip to a uv project"],"tags":[]},{"location":"guides/migration/pip-to-project/#the-uv-lockfile","level":3,"title":"The uv lockfile","text":"uv uses a lockfile (uv.lock) file to lock package versions. The format of this file is specific to uv, allowing uv to support advanced features. It replaces requirements.txt files.
The lockfile will be automatically created and populated when adding dependencies, but you can explicitly create it with uv lock.
Unlike requirements.txt files, the uv.lock file can represent arbitrary groups of dependencies, so multiple files are not needed to lock development dependencies.
The uv lockfile is always universal, so multiple files are not needed to lock dependencies for each platform. This ensures that all developers are using consistent, locked versions of dependencies regardless of their machine.
The uv lockfile also supports concepts like pinning packages to specific indexes, which is not representable in requirements.txt files.
Tip
If you only need to lock for a subset of platforms, use the tool.uv.environments setting to limit the resolution and lockfile.
To learn more, see the lockfile documentation.
","path":["Guides","Migration","Migrating from pip to a uv project"],"tags":[]},{"location":"guides/migration/pip-to-project/#importing-requirements-files","level":3,"title":"Importing requirements files","text":"First, create a pyproject.toml if you have not already:
$ uv init\n
Then, the easiest way to import requirements is with uv add:
$ uv add -r requirements.in\n
However, there is some nuance to this transition. Notice we used the requirements.in file, which does not pin to exact versions of packages so uv will solve for new versions of these packages. You may want to continue using your previously locked versions from your requirements.txt so, when switching over to uv, none of your dependency versions change.
The solution is to add your locked versions as constraints. uv supports using these on add to preserve locked versions:
$ uv add -r requirements.in -c requirements.txt\n
Your existing versions will be retained when producing a uv.lock file.
","path":["Guides","Migration","Migrating from pip to a uv project"],"tags":[]},{"location":"guides/migration/pip-to-project/#importing-platform-specific-constraints","level":4,"title":"Importing platform-specific constraints","text":"If your platform-specific dependencies have been compiled into separate files, you can still transition to a universal lockfile. However, you cannot just use -c to specify constraints from your existing platform-specific requirements.txt files because they do not include markers describing the environment and will consequently conflict.
To add the necessary markers, use uv pip compile to convert your existing files. For example, given the following:
requirements-win.txtcolorama==0.4.6\n # via tqdm\ntqdm==4.67.1\n # via -r requirements.in\n
The markers can be added with:
$ uv pip compile requirements.in -o requirements-win.txt --python-platform windows --no-strip-markers\n
Notice the resulting output includes a Windows marker on colorama:
requirements-win.txtcolorama==0.4.6 ; sys_platform == 'win32'\n # via tqdm\ntqdm==4.67.1\n # via -r requirements.in\n
When using -o, uv will constrain the versions to match the existing output file, if it can.
Markers can be added for other platforms by changing the --python-platform and -o values for each requirements file you need to import, e.g., to linux and macos.
Once each requirements.txt file has been transformed, the dependencies can be imported to the pyproject.toml and uv.lock with uv add:
$ uv add -r requirements.in -c requirements-win.txt -c requirements-linux.txt\n
","path":["Guides","Migration","Migrating from pip to a uv project"],"tags":[]},{"location":"guides/migration/pip-to-project/#importing-development-dependency-files","level":4,"title":"Importing development dependency files","text":"As discussed in the development dependencies section, it's common to have groups of dependencies for development purposes.
To import development dependencies, use the --dev flag during uv add:
$ uv add --dev -r requirements-dev.in -c requirements-dev.txt\n
If the requirements-dev.in includes the parent requirements.in via -r, it will need to be stripped to avoid adding the base requirements to the dev dependency group. The following example uses sed to strip lines that start with -r, then pipes the result to uv add:
$ sed '/^-r /d' requirements-dev.in | uv add --dev -r - -c requirements-dev.txt\n
In addition to the dev dependency group, uv supports arbitrary group names. For example, if you also have a dedicated set of dependencies for building your documentation, those can be imported to a docs group:
$ uv add -r requirements-docs.in -c requirements-docs.txt --group docs\n
","path":["Guides","Migration","Migrating from pip to a uv project"],"tags":[]},{"location":"guides/migration/pip-to-project/#project-environments","level":3,"title":"Project environments","text":"Unlike pip, uv is not centered around the concept of an \"active\" virtual environment. Instead, uv uses a dedicated virtual environment for each project in a .venv directory. This environment is automatically managed, so when you run a command, like uv add, the environment is synced with the project dependencies.
The preferred way to execute commands in the environment is with uv run, e.g.:
$ uv run pytest\n
Prior to every uv run invocation, uv will verify that the lockfile is up-to-date with the pyproject.toml, and that the environment is up-to-date with the lockfile, keeping your project in-sync without the need for manual intervention. uv run guarantees that your command is run in a consistent, locked environment.
The project environment can also be explicitly created with uv sync, e.g., for use with editors.
Note
When in projects, uv will prefer a .venv in the project directory and ignore the active environment as declared by the VIRTUAL_ENV variable by default. You can opt-in to using the active environment with the --active flag.
To learn more, see the project environment documentation.
","path":["Guides","Migration","Migrating from pip to a uv project"],"tags":[]},{"location":"guides/migration/pip-to-project/#next-steps","level":2,"title":"Next steps","text":"Now that you've migrated to uv, take a look at the project concept page for more details about uv projects.
","path":["Guides","Migration","Migrating from pip to a uv project"],"tags":[]},{"location":"pip/","level":1,"title":"The pip interface","text":"uv provides a drop-in replacement for common pip, pip-tools, and virtualenv commands. These commands work directly with the virtual environment, in contrast to uv's primary interfaces where the virtual environment is managed automatically. The uv pip interface exposes the speed and functionality of uv to power users and projects that are not ready to transition away from pip and pip-tools.
The following sections discuss the basics of using uv pip:
- Creating and using environments
- Installing and managing packages
- Inspecting environments and packages
- Declaring package dependencies
- Locking and syncing environments
Please note these commands do not exactly implement the interfaces and behavior of the tools they are based on. The further you stray from common workflows, the more likely you are to encounter differences. Consult the pip-compatibility guide for details.
Important
uv does not rely on or invoke pip. The pip interface is named as such to highlight its dedicated purpose of providing low-level commands that match pip's interface and to separate it from the rest of uv's commands which operate at a higher level of abstraction.
","path":["Concepts","The pip interface"],"tags":[]},{"location":"pip/compatibility/","level":1,"title":"Compatibility with pip and pip-tools","text":"uv is designed as a drop-in replacement for common pip and pip-tools workflows.
Informally, the intent is such that existing pip and pip-tools users can switch to uv without making meaningful changes to their packaging workflows; and, in most cases, swapping out pip install for uv pip install should \"just work\".
However, uv is not intended to be an exact clone of pip, and the further you stray from common pip workflows, the more likely you are to encounter differences in behavior. In some cases, those differences may be known and intentional; in others, they may be the result of implementation details; and in others, they may be bugs.
This document outlines the known differences between uv and pip, along with rationale, workarounds, and a statement of intent for compatibility in the future.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#configuration-files-and-environment-variables","level":2,"title":"Configuration files and environment variables","text":"uv does not read configuration files or environment variables that are specific to pip, like pip.conf or PIP_INDEX_URL.
Reading configuration files and environment variables intended for other tools has a number of drawbacks:
- It requires bug-for-bug compatibility with the target tool, since users end up relying on bugs in the format, the parser, etc.
- If the target tool changes the format in some way, uv is then locked-in to changing it in equivalent ways.
- If that configuration is versioned in some way, uv would need to know which version of the target tool the user is expecting to use.
- It prevents uv from introducing any settings or configuration that don't exist in the target tool, since otherwise
pip.conf (or similar) would no longer be usable with pip. - It can lead to user confusion, since uv would be reading settings that don't actually affect its behavior, and many users may not expect uv to read configuration files intended for other tools.
Instead, uv supports its own environment variables, like UV_INDEX_URL. uv also supports persistent configuration in a uv.toml file or a [tool.uv.pip] section of pyproject.toml. For more information, see Configuration files.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#pre-release-compatibility","level":2,"title":"Pre-release compatibility","text":"By default, uv will accept pre-release versions during dependency resolution in two cases:
- If the package is a direct dependency, and its version markers include a pre-release specifier (e.g.,
flask>=2.0.0rc1). - If all published versions of a package are pre-releases.
If dependency resolution fails due to a transitive pre-release, uv will prompt the user to re-run with --prerelease allow, to allow pre-releases for all dependencies.
Alternatively, you can add the transitive dependency to your requirements.in file with pre-release specifier (e.g., flask>=2.0.0rc1) to opt in to pre-release support for that specific dependency.
In sum, uv needs to know upfront whether the resolver should accept pre-releases for a given package. pip, meanwhile, may respect pre-release identifiers in transitive dependencies depending on the order in which the resolver encounters the relevant specifiers (#1641).
Pre-releases are notoriously difficult to model, and are a frequent source of bugs in packaging tools. Even pip, which is viewed as a reference implementation, has a number of open questions around pre-release handling (#12469, #12470, #40505, etc.). uv's pre-release handling is intentionally limited and intentionally requires user opt-in for pre-releases, to ensure correctness.
In the future, uv may support pre-release identifiers in transitive dependencies. However, it's likely contingent on evolution in the Python packaging specifications. The existing PEPs do not cover \"dependency resolution\" and are instead focused on behavior for a single version specifier. As such, there are unresolved questions around the correct and intended behavior for pre-releases in the packaging ecosystem more broadly.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#packages-that-exist-on-multiple-indexes","level":2,"title":"Packages that exist on multiple indexes","text":"In both uv and pip, users can specify multiple package indexes from which to search for the available versions of a given package. However, uv and pip differ in how they handle packages that exist on multiple indexes.
For example, imagine that a company publishes an internal version of requests on a private index (--extra-index-url), but also allows installing packages from PyPI by default. In this case, the private requests would conflict with the public requests on PyPI.
When uv searches for a package across multiple indexes, it will iterate over the indexes in order (preferring the --extra-index-url over the default index), and stop searching as soon as it finds a match. This means that if a package exists on multiple indexes, uv will limit its candidate versions to those present in the first index that contains the package.
pip, meanwhile, will combine the candidate versions from all indexes, and select the best version from the combined set, though it makes no guarantees around the order in which it searches indexes, and expects that packages are unique up to name and version, even across indexes.
uv's behavior is such that if a package exists on an internal index, it should always be installed from the internal index, and never from PyPI. The intent is to prevent \"dependency confusion\" attacks, in which an attacker publishes a malicious package on PyPI with the same name as an internal package, thus causing the malicious package to be installed instead of the internal package. See, for example, the torchtriton attack from December 2022.
As of v0.1.39, users can opt in to pip-style behavior for multiple indexes via the --index-strategy command-line option, or the UV_INDEX_STRATEGY environment variable, which supports the following values:
first-index (default): Search for each package across all indexes, limiting the candidate versions to those present in the first index that contains the package, prioritizing the --extra-index-url indexes over the default index URL.unsafe-first-match: Search for each package across all indexes, but prefer the first index with a compatible version, even if newer versions are available on other indexes.unsafe-best-match: Search for each package across all indexes, and select the best version from the combined set of candidate versions.
While unsafe-best-match is the closest to pip's behavior, it exposes users to the risk of \"dependency confusion\" attacks.
uv also supports pinning packages to dedicated indexes (see: Indexes), such that a given package is always installed from a specific index.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#pep-517-build-isolation","level":2,"title":"PEP 517 build isolation","text":"uv uses PEP 517 build isolation by default (akin to pip install --use-pep517), following pypa/build and in anticipation of pip defaulting to PEP 517 builds in the future (pypa/pip#9175).
If a package fails to install due to a missing build-time dependency, try using a newer version of the package; if the problem persists, consider filing an issue with the package maintainer, requesting that they update the packaging setup to declare the correct PEP 517 build-time dependencies.
As an escape hatch, you can preinstall a package's build dependencies, then run uv pip install with --no-build-isolation, as in:
uv pip install wheel && uv pip install --no-build-isolation biopython==1.77\n
For a list of packages that are known to fail under PEP 517 build isolation, see #2252.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#transitive-url-dependencies","level":2,"title":"Transitive URL dependencies","text":"While uv includes first-class support for URL dependencies (e.g., ruff @ https://...), it differs from pip in its handling of transitive URL dependencies in two ways.
First, uv makes the assumption that non-URL dependencies do not introduce URL dependencies into the resolution. In other words, it assumes that dependencies fetched from a registry do not themselves depend on URLs. If a non-URL dependency does introduce a URL dependency, uv will reject the URL dependency during resolution. (Note that PyPI does not allow published packages to depend on URL dependencies; other registries may be more permissive.)
Second, if a constraint (--constraint) or override (--override) is defined using a direct URL dependency, and the constrained package has a direct URL dependency of its own, uv may reject that transitive direct URL dependency during resolution, if the URL isn't referenced elsewhere in the set of input requirements.
If uv rejects a transitive URL dependency, the best course of action is to provide the URL dependency as a direct dependency in the relevant pyproject.toml or requirement.in file, as the above constraints do not apply to direct dependencies.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#virtual-environments-by-default","level":2,"title":"Virtual environments by default","text":"uv pip install and uv pip sync are designed to work with virtual environments by default.
Specifically, uv will always install packages into the currently active virtual environment, or search for a virtual environment named .venv in the current directory or any parent directory (even if it is not activated).
This differs from pip, which will install packages into a global environment if no virtual environment is active, and will not search for inactive virtual environments.
In uv, you can install into non-virtual environments by providing a path to a Python executable via the --python /path/to/python option, or via the --system flag, which installs into the first Python interpreter found on the PATH, like pip.
In other words, uv inverts the default, requiring explicit opt-in to installing into the system Python, which can lead to breakages and other complications, and should only be done in limited circumstances.
For more, see \"Using arbitrary Python environments\".
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#resolution-strategy","level":2,"title":"Resolution strategy","text":"For a given set of dependency specifiers, it's often the case that there is no single \"correct\" set of packages to install. Instead, there are many valid sets of packages that satisfy the specifiers.
Neither pip nor uv make any guarantees about the exact set of packages that will be installed; only that the resolution will be consistent, deterministic, and compliant with the specifiers. As such, in some cases, pip and uv will yield different resolutions; however, both resolutions should be equally valid.
For example, consider:
requirements.instarlette\nfastapi\n
At time of writing, the most recent starlette version is 0.37.2, and the most recent fastapi version is 0.110.0. However, fastapi==0.110.0 also depends on starlette, and introduces an upper bound: starlette>=0.36.3,<0.37.0.
If a resolver prioritizes including the most recent version of starlette, it would need to use an older version of fastapi that excludes the upper bound on starlette. In practice, this requires falling back to fastapi==0.1.17:
requirements.txt# This file was autogenerated by uv via the following command:\n# uv pip compile requirements.in\nannotated-types==0.6.0\n # via pydantic\nanyio==4.3.0\n # via starlette\nfastapi==0.1.17\nidna==3.6\n # via anyio\npydantic==2.6.3\n # via fastapi\npydantic-core==2.16.3\n # via pydantic\nsniffio==1.3.1\n # via anyio\nstarlette==0.37.2\n # via fastapi\ntyping-extensions==4.10.0\n # via\n # pydantic\n # pydantic-core\n
Alternatively, if a resolver prioritizes including the most recent version of fastapi, it would need to use an older version of starlette that satisfies the upper bound. In practice, this requires falling back to starlette==0.36.3:
requirements.txt# This file was autogenerated by uv via the following command:\n# uv pip compile requirements.in\nannotated-types==0.6.0\n # via pydantic\nanyio==4.3.0\n # via starlette\nfastapi==0.110.0\nidna==3.6\n # via anyio\npydantic==2.6.3\n # via fastapi\npydantic-core==2.16.3\n # via pydantic\nsniffio==1.3.1\n # via anyio\nstarlette==0.36.3\n # via fastapi\ntyping-extensions==4.10.0\n # via\n # fastapi\n # pydantic\n # pydantic-core\n
When uv resolutions differ from pip in undesirable ways, it's often a sign that the specifiers are too loose, and that the user should consider tightening them. For example, in the case of starlette and fastapi, the user could require fastapi>=0.110.0.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#pip-check","level":2,"title":"pip check","text":"At present, uv pip check will surface the following diagnostics:
- A package has no
METADATA file, or the METADATA file can't be parsed. - A package has a
Requires-Python that doesn't match the Python version of the running interpreter. - A package has a dependency on a package that isn't installed.
- A package has a dependency on a package that's installed, but at an incompatible version.
- Multiple versions of a package are installed in the virtual environment.
In some cases, uv pip check will surface diagnostics that pip check does not, and vice versa. For example, unlike uv pip check, pip check will not warn when multiple versions of a package are installed in the current environment.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#-user-and-the-user-install-scheme","level":2,"title":"--user and the user install scheme","text":"uv does not support the --user flag, which installs packages based on the user install scheme. Instead, we recommend the use of virtual environments to isolate package installations.
Additionally, pip will fall back to the user install scheme if it detects that the user does not have write permissions to the target directory, as is the case on some systems when installing into the system Python. uv does not implement any such fallback.
For more, see #2077.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#-only-binary-enforcement","level":2,"title":"--only-binary enforcement","text":"The --only-binary argument is used to restrict installation to pre-built binary distributions. When --only-binary :all: is provided, both pip and uv will refuse to build source distributions from PyPI and other registries.
However, when a dependency is provided as a direct URL (e.g., uv pip install https://...), pip does not enforce --only-binary, and will build source distributions for all such packages.
uv, meanwhile, does enforce --only-binary for direct URL dependencies, with one exception: given uv pip install https://... --only-binary flask, uv will build the source distribution at the given URL if it cannot infer the package name ahead of time, since uv can't determine whether the package is \"allowed\" in such cases without building its metadata.
Both pip and uv allow editables requirements to be built and installed even when --only-binary is provided. For example, uv pip install -e . --only-binary :all: is allowed.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#-no-binary-enforcement","level":2,"title":"--no-binary enforcement","text":"The --no-binary argument is used to restrict installation to source distributions. When --no-binary is provided, uv will refuse to install pre-built binary distributions, but will reuse any binary distributions that are already present in the local cache.
Additionally, and in contrast to pip, uv's resolver will still read metadata from pre-built binary distributions when --no-binary is provided.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#manylinux_compatible-enforcement","level":2,"title":"manylinux_compatible enforcement","text":"PEP 600 describes a mechanism through which Python distributors can opt out of manylinux compatibility by defining a manylinux_compatible function on the _manylinux standard library module.
uv respects manylinux_compatible, but only tests against the current glibc version, and applies the return value of manylinux_compatible globally.
In other words, if manylinux_compatible returns True, uv will treat the system as manylinux-compatible; if it returns False, uv will treat the system as manylinux-incompatible, without calling manylinux_compatible for every glibc version.
This approach is not a complete implementation of the spec, but is compatible with common blanket manylinux_compatible implementations like no-manylinux:
from __future__ import annotations\nmanylinux1_compatible = False\nmanylinux2010_compatible = False\nmanylinux2014_compatible = False\n\n\ndef manylinux_compatible(*_, **__): # PEP 600\n return False\n
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#bytecode-compilation","level":2,"title":"Bytecode compilation","text":"Unlike pip, uv does not compile .py files to .pyc files during installation by default (i.e., uv does not create or populate __pycache__ directories). To enable bytecode compilation during installs, pass the --compile-bytecode flag to uv pip install or uv pip sync, or set the UV_COMPILE_BYTECODE environment variable to 1.
Skipping bytecode compilation can be undesirable in workflows; for example, we recommend enabling bytecode compilation in Docker builds to improve startup times (at the cost of increased build times).
As bytecode compilation suppresses various warnings issued by the Python interpreter, in rare cases you may seen SyntaxWarning or DeprecationWarning messages when running Python code that was installed with uv that do not appear when using pip. These are valid warnings, but are typically hidden by the bytecode compilation process, and can either be ignored, fixed upstream, or similarly suppressed by enabling bytecode compilation in uv.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#strictness-and-spec-enforcement","level":2,"title":"Strictness and spec enforcement","text":"uv tends to be stricter than pip, and will often reject packages that pip would install. For example, uv rejects HTML indexes with invalid URL fragments (see: PEP 503), while pip will ignore such fragments.
In some cases, uv implements lenient behavior for popular packages that are known to have specific spec compliance issues.
If uv rejects a package that pip would install due to a spec violation, the best course of action is to first attempt to install a newer version of the package; and, if that fails, to report the issue to the package maintainer.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#pip-command-line-options-and-subcommands","level":2,"title":"pip command-line options and subcommands","text":"uv does not support the complete set of pip's command-line options and subcommands, although it does support a large subset.
Missing options and subcommands are prioritized based on user demand and the complexity of the implementation, and tend to be tracked in individual issues. For example:
--trusted-host--user
If you encounter a missing option or subcommand, please search the issue tracker to see if it has already been reported, and if not, consider opening a new issue. Feel free to upvote any existing issues to convey your interest.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#registry-authentication","level":2,"title":"Registry authentication","text":"uv does not support pip's auto or import options for --keyring-provider. At present, only the subprocess option is supported.
Unlike pip, uv does not enable keyring authentication by default.
Unlike pip, uv does not wait until a request returns an HTTP 401 before searching for authentication. uv attaches authentication to all requests for hosts with credentials available.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#egg-support","level":2,"title":"egg support","text":"uv does not support features that are considered legacy or deprecated in pip. For example, uv does not support .egg-style distributions.
However, uv does have partial support for (1) .egg-info-style distributions (which are occasionally found in Docker images and Conda environments) and (2) legacy editable .egg-link-style distributions.
Specifically, uv does not support installing new .egg-info- or .egg-link-style distributions, but will respect any such existing distributions during resolution, list them with uv pip list and uv pip freeze, and uninstall them with uv pip uninstall.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#build-constraints","level":2,"title":"Build constraints","text":"When constraints are provided via --constraint (or UV_CONSTRAINT), uv will not apply the constraints when resolving build dependencies (i.e., to build a source distribution). Instead, build constraints should be provided via the dedicated --build-constraint (or UV_BUILD_CONSTRAINT) setting.
pip, meanwhile, applies constraints to build dependencies when specified via PIP_CONSTRAINT, but not when provided via --constraint on the command line.
For example, to ensure that setuptools 60.0.0 is used to build any packages with a build dependency on setuptools, use --build-constraint, rather than --constraint.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#pip-compile-defaults","level":2,"title":"pip compile defaults","text":"There are a few small but notable differences in the default behaviors of pip compile and pip-tools.
By default, uv does not write the compiled requirements to an output file. Instead, uv requires that the user specify an output file explicitly with the -o or --output-file option.
By default, uv strips extras when outputting the compiled requirements. In other words, uv defaults to --strip-extras, while pip-compile defaults to --no-strip-extras. pip-compile is scheduled to change this default in the next major release (v8.0.0), at which point both tools will default to --strip-extras. To retain extras with uv, pass the --no-strip-extras flag to uv pip compile.
By default, uv does not write any index URLs to the output file, while pip-compile outputs any --index-url or --extra-index-url that does not match the default (PyPI). To include index URLs in the output file, pass the --emit-index-url flag to uv pip compile. Unlike pip-compile, uv will include all index URLs when --emit-index-url is passed, including the default index URL.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#requires-python-upper-bounds","level":2,"title":"requires-python upper bounds","text":"When evaluating requires-python ranges for dependencies, uv only considers lower bounds and ignores upper bounds entirely. For example, >=3.8, <4 is treated as >=3.8. Respecting upper bounds on requires-python often leads to formally correct but practically incorrect resolutions, as, e.g., resolvers will backtrack to the first published version that omits the upper bound (see: Requires-Python upper limits).
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#requires-python-specifiers","level":2,"title":"requires-python specifiers","text":"When evaluating Python versions against requires-python specifiers, uv truncates the candidate version to the major, minor, and patch components, ignoring (e.g.) pre-release and post-release identifiers.
For example, a project that declares requires-python: >=3.13 will accept Python 3.13.0b1. While 3.13.0b1 is not strictly greater than 3.13, it is greater than 3.13 when the pre-release identifier is omitted.
While this is not strictly compliant with PEP 440, it is consistent with pip.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#package-priority","level":2,"title":"Package priority","text":"There are usually many possible solutions given a set of requirements, and a resolver must choose between them. uv's resolver and pip's resolver have a different set of package priorities. While both resolvers use the user-provided order as one of their priorities, pip has additional priorities that uv does not have. Hence, uv is more likely to be affected by a change in user order than pip is.
For example, uv pip install foo bar prioritizes newer versions of foo over bar and could result in a different resolution than uv pip install bar foo. Similarly, this behavior applies to the ordering of requirements in input files for uv pip compile.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#wheel-filename-and-metadata-validation","level":2,"title":"Wheel filename and metadata validation","text":"By default, uv will reject wheels whose filenames are inconsistent with the wheel metadata inside the file. For example, a wheel named foo-1.0.0-py3-none-any.whl that contains metadata indicating the version is 1.0.1 will be rejected by uv, but accepted by pip.
To force uv to accept such wheels, set UV_SKIP_WHEEL_FILENAME_CHECK=1 in the environment.
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compatibility/#package-name-normalization","level":2,"title":"Package name normalization","text":"By default, uv normalizes package names to match their PEP 503-compliant forms and uses those normalized names in all output contexts. This differs from pip, which tends to preserve the verbatim package name as published on the registry.
For example, uv pip list displays normalized packages names (e.g., docstring-parser), while pip list displays non-normalized package names (e.g., docstring_parser):
(venv) $ diff --side-by-side <(pip list) <(uv pip list)\nPackage Version Package Version\n---------------- ------- ---------------- -------\ndocstring_parser 0.16 | docstring-parser 0.16\njaraco.classes 3.4.0 | jaraco-classes 3.4.0\nmore-itertools 10.7.0 more-itertools 10.7.0\npip 25.1 pip 25.1\nPyMuPDFb 1.24.10 | pymupdfb 1.24.10\nPyPDF2 3.0.1 | pypdf2 3.0.1\n
","path":["Concepts","The pip interface","Compatibility with pip and pip-tools"],"tags":[]},{"location":"pip/compile/","level":1,"title":"Locking environments","text":"Locking is to take a dependency, e.g., ruff, and write an exact version to use to a file. When working with many dependencies, it is useful to lock the exact versions so the environment can be reproduced. Without locking, the versions of dependencies could change over time, when using a different tool, or across platforms.
","path":["Concepts","The pip interface","Locking environments"],"tags":[]},{"location":"pip/compile/#locking-requirements","level":2,"title":"Locking requirements","text":"uv allows dependencies to be locked in the requirements.txt format. It is recommended to use the standard pyproject.toml to define dependencies, but other dependency formats are supported as well. See the documentation on declaring dependencies for more details on how to define dependencies.
To lock dependencies declared in a pyproject.toml:
$ uv pip compile pyproject.toml -o requirements.txt\n
Note by default the uv pip compile output is just displayed and --output-file / -o argument is needed to write to a file.
To lock dependencies declared in a requirements.in:
$ uv pip compile requirements.in -o requirements.txt\n
To lock dependencies declared in multiple files:
$ uv pip compile pyproject.toml requirements-dev.in -o requirements-dev.txt\n
uv also supports legacy setup.py and setup.cfg formats. To lock dependencies declared in a setup.py:
$ uv pip compile setup.py -o requirements.txt\n
To lock dependencies from stdin, use -:
$ echo \"ruff\" | uv pip compile -\n
To lock with optional dependencies enabled, e.g., the \"foo\" extra:
$ uv pip compile pyproject.toml --extra foo\n
To lock with all optional dependencies enabled:
$ uv pip compile pyproject.toml --all-extras\n
Note extras are not supported with the requirements.in format.
To lock a dependency group in the current project directory's pyproject.toml, for example the group foo:
$ uv pip compile --group foo\n
Important
A --group flag has to be added to pip-tools' pip compile, although they're considering it. We expect to support whatever syntax and semantics they adopt.
To specify the project directory where groups should be sourced from:
$ uv pip compile --project some/path/ --group foo --group bar\n
Alternatively, you can specify a path to a pyproject.toml for each group:
$ uv pip compile --group some/path/pyproject.toml:foo --group other/pyproject.toml:bar\n
Note
--group flags do not apply to other specified sources. For instance, uv pip compile some/path/pyproject.toml --group foo sources foo from ./pyproject.toml and not some/path/pyproject.toml.
","path":["Concepts","The pip interface","Locking environments"],"tags":[]},{"location":"pip/compile/#upgrading-requirements","level":2,"title":"Upgrading requirements","text":"When using an output file, uv will consider the versions pinned in an existing output file. If a dependency is pinned it will not be upgraded on a subsequent compile run. For example:
$ echo \"ruff==0.3.0\" > requirements.txt\n$ echo \"ruff\" | uv pip compile - -o requirements.txt\n# This file was autogenerated by uv via the following command:\n# uv pip compile - -o requirements.txt\nruff==0.3.0\n
To upgrade a dependency, use the --upgrade-package flag:
$ uv pip compile - -o requirements.txt --upgrade-package ruff\n
To upgrade all dependencies, there is an --upgrade flag.
","path":["Concepts","The pip interface","Locking environments"],"tags":[]},{"location":"pip/compile/#syncing-an-environment","level":2,"title":"Syncing an environment","text":"Dependencies can be installed directly from their definition files or from compiled requirements.txt files with uv pip install. See the documentation on installing packages from files for more details.
When installing with uv pip install, packages that are already installed will not be removed unless they conflict with the lockfile. This means that the environment can have dependencies that aren't declared in the lockfile, which isn't great for reproducibility. To ensure the environment exactly matches the lockfile, use uv pip sync instead.
To sync an environment with a requirements.txt file:
$ uv pip sync requirements.txt\n
To sync an environment with a PEP 751 pylock.toml file:
$ uv pip sync pylock.toml\n
","path":["Concepts","The pip interface","Locking environments"],"tags":[]},{"location":"pip/compile/#adding-constraints","level":2,"title":"Adding constraints","text":"Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package. Constraints can be used to add bounds to dependencies that are not dependencies of the current project.
To define a constraint, define a bound for a package:
constraints.txtpydantic<2.0\n
To use a constraints file:
$ uv pip compile requirements.in --constraint constraints.txt\n
Note that multiple constraints can be defined in each file and multiple files can be used.
uv will also read constraint-dependencies from the pyproject.toml at the workspace root, and append them to those specified in the constraints file.
","path":["Concepts","The pip interface","Locking environments"],"tags":[]},{"location":"pip/compile/#adding-build-constraints","level":2,"title":"Adding build constraints","text":"Similar to constraints, but specifically for build-time dependencies, including those required when building runtime dependencies.
Build constraint files are requirements.txt-like files that only control the version of a build-time requirement. However, including a package in a build constraints file will not trigger its installation at build time; instead, constraints apply only when the package is required as a direct or transitive build-time dependency. Build constraints can be used to add bounds to dependencies that are not explicitly declared as build-time dependencies of the current project.
For example, if a package defines its build dependencies as follows:
pyproject.toml[build-system]\nrequires = [\"setuptools\"]\nbuild-backend = \"setuptools.build_meta\"\n
Build constraints could be used to ensure that a specific version of setuptools is used for every package in the workspace:
build-constraints.txtsetuptools==75.0.0\n
uv will also read build-constraint-dependencies from the pyproject.toml at the workspace root, and append them to those specified in the build constraints file.
","path":["Concepts","The pip interface","Locking environments"],"tags":[]},{"location":"pip/compile/#overriding-dependency-versions","level":2,"title":"Overriding dependency versions","text":"Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.
While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.
Overrides are most often used to remove upper bounds from a transitive dependency. For example, if a requires c>=1.0,<2.0 and b requires c>=2.0 and the current project requires a and b then the dependencies cannot be resolved.
To define an override, define the new requirement for the problematic package:
overrides.txtc>=2.0\n
To use an overrides file:
$ uv pip compile requirements.in --override overrides.txt\n
Now, resolution can succeed. However, note that if a is correct that it does not support c>=2.0 then a runtime error will likely be encountered when using the packages.
Note that multiple overrides can be defined in each file and multiple files can be used.
","path":["Concepts","The pip interface","Locking environments"],"tags":[]},{"location":"pip/dependencies/","level":1,"title":"Declaring dependencies","text":"It is best practice to declare dependencies in a static file instead of modifying environments with ad-hoc installations. Once dependencies are defined, they can be locked to create a consistent, reproducible environment.
","path":["Concepts","The pip interface","Declaring dependencies"],"tags":[]},{"location":"pip/dependencies/#using-pyprojecttoml","level":2,"title":"Using pyproject.toml","text":"The pyproject.toml file is the Python standard for defining configuration for a project.
To define project dependencies in a pyproject.toml file:
pyproject.toml[project]\ndependencies = [\n \"httpx\",\n \"ruff>=0.3.0\"\n]\n
To define optional dependencies in a pyproject.toml file:
pyproject.toml[project.optional-dependencies]\ncli = [\n \"rich\",\n \"click\",\n]\n
Each of the keys defines an \"extra\", which can be installed using the --extra and --all-extras flags or package[<extra>] syntax. See the documentation on installing packages for more details.
See the official pyproject.toml guide for more details on getting started with a pyproject.toml.
","path":["Concepts","The pip interface","Declaring dependencies"],"tags":[]},{"location":"pip/dependencies/#using-requirementsin","level":2,"title":"Using requirements.in","text":"It is also common to use a lightweight requirements.txt format to declare the dependencies for the project. Each requirement is defined on its own line. Commonly, this file is called requirements.in to distinguish it from requirements.txt which is used for the locked dependencies.
To define dependencies in a requirements.in file:
requirements.inhttpx\nruff>=0.3.0\n
Optional dependencies groups are not supported in this format.
","path":["Concepts","The pip interface","Declaring dependencies"],"tags":[]},{"location":"pip/environments/","level":1,"title":"Using Python environments","text":"Each Python installation has an environment that is active when Python is used. Packages can be installed into an environment to make their modules available from your Python scripts. Generally, it is considered best practice not to modify a Python installation's environment. This is especially important for Python installations that come with the operating system which often manage the packages themselves. A virtual environment is a lightweight way to isolate packages from a Python installation's environment. Unlike pip, uv requires using a virtual environment by default.
","path":["Concepts","The pip interface","Using Python environments"],"tags":[]},{"location":"pip/environments/#creating-a-virtual-environment","level":2,"title":"Creating a virtual environment","text":"uv supports creating virtual environments, e.g., to create a virtual environment at .venv:
$ uv venv\n
A specific name or path can be specified, e.g., to create a virtual environment at my-name:
$ uv venv my-name\n
A Python version can be requested, e.g., to create a virtual environment with Python 3.11:
$ uv venv --python 3.11\n
Note this requires the requested Python version to be available on the system. However, if unavailable, uv will download Python for you. See the Python version documentation for more details.
","path":["Concepts","The pip interface","Using Python environments"],"tags":[]},{"location":"pip/environments/#using-a-virtual-environment","level":2,"title":"Using a virtual environment","text":"When using the default virtual environment name, uv will automatically find and use the virtual environment during subsequent invocations.
$ uv venv\n\n$ # Install a package in the new virtual environment\n$ uv pip install ruff\n
The virtual environment can be \"activated\" to make its packages available:
macOS and LinuxWindows $ source .venv/bin/activate\n
PS> .venv\\Scripts\\activate\n
Note
The default activation script on Unix is for POSIX compliant shells like sh, bash, or zsh. There are additional activation scripts for common alternative shells.
fishcsh / tcshNushell $ source .venv/bin/activate.fish\n
$ source .venv/bin/activate.csh\n
$ use .venv\\Scripts\\activate.nu\n
","path":["Concepts","The pip interface","Using Python environments"],"tags":[]},{"location":"pip/environments/#deactivating-an-environment","level":2,"title":"Deactivating an environment","text":"To exit a virtual environment, use the deactivate command:
$ deactivate\n
","path":["Concepts","The pip interface","Using Python environments"],"tags":[]},{"location":"pip/environments/#using-arbitrary-python-environments","level":2,"title":"Using arbitrary Python environments","text":"Since uv has no dependency on Python, it can install into virtual environments other than its own. For example, setting VIRTUAL_ENV=/path/to/venv will cause uv to install into /path/to/venv, regardless of where uv is installed. Note that if VIRTUAL_ENV is set to a directory that is not a PEP 405 compliant virtual environment, it will be ignored.
uv can also install into arbitrary, even non-virtual environments, with the --python argument provided to uv pip sync or uv pip install. For example, uv pip install --python /path/to/python will install into the environment linked to the /path/to/python interpreter.
For convenience, uv pip install --system will install into the system Python environment. Using --system is roughly equivalent to uv pip install --python $(which python), but note that executables that are linked to virtual environments will be skipped. Although we generally recommend using virtual environments for dependency management, --system is appropriate in continuous integration and containerized environments.
The --system flag is also used to opt in to mutating system environments. For example, the --python argument can be used to request a Python version (e.g., --python 3.12), and uv will search for an interpreter that meets the request. If uv finds a system interpreter (e.g., /usr/lib/python3.12), then the --system flag is required to allow modification of this non-virtual Python environment. Without the --system flag, uv will ignore any interpreters that are not in virtual environments. Conversely, when the --system flag is provided, uv will ignore any interpreters that are in virtual environments.
Installing into system Python across platforms and distributions is notoriously difficult. uv supports the common cases, but will not work in all cases. For example, installing into system Python on Debian prior to Python 3.10 is unsupported due to the distribution's patching of distutils (but not sysconfig). While we always recommend the use of virtual environments, uv considers them to be required in these non-standard environments.
If uv is installed in a Python environment, e.g., with pip, it can still be used to modify other environments. However, when invoked with python -m uv, uv will default to using the parent interpreter's environment. Invoking uv via Python adds startup overhead and is not recommended for general usage.
uv itself does not depend on Python, but it does need to locate a Python environment to (1) install dependencies into the environment and (2) build source distributions.
","path":["Concepts","The pip interface","Using Python environments"],"tags":[]},{"location":"pip/environments/#discovery-of-python-environments","level":2,"title":"Discovery of Python environments","text":"When running a command that mutates an environment such as uv pip sync or uv pip install, uv will search for a virtual environment in the following order:
- An activated virtual environment based on the
VIRTUAL_ENV environment variable. - An activated Conda environment based on the
CONDA_PREFIX environment variable. - A virtual environment at
.venv in the current directory, or in the nearest parent directory.
If no virtual environment is found, uv will prompt the user to create one in the current directory via uv venv.
If the --system flag is included, uv will skip virtual environments search for an installed Python version. Similarly, when running a command that does not mutate the environment such as uv pip compile, uv does not require a virtual environment — however, a Python interpreter is still required. See the documentation on Python discovery for details on the discovery of installed Python versions.
","path":["Concepts","The pip interface","Using Python environments"],"tags":[]},{"location":"pip/inspection/","level":1,"title":"Inspecting environments","text":"","path":["Concepts","The pip interface","Inspecting environments"],"tags":[]},{"location":"pip/inspection/#listing-installed-packages","level":2,"title":"Listing installed packages","text":"To list all the packages in the environment:
$ uv pip list\n
To list the packages in a JSON format:
$ uv pip list --format json\n
To list all the packages in the environment in a requirements.txt format:
$ uv pip freeze\n
","path":["Concepts","The pip interface","Inspecting environments"],"tags":[]},{"location":"pip/inspection/#inspecting-a-package","level":2,"title":"Inspecting a package","text":"To show information about an installed package, e.g., numpy:
$ uv pip show numpy\n
Multiple packages can be inspected at once.
","path":["Concepts","The pip interface","Inspecting environments"],"tags":[]},{"location":"pip/inspection/#verifying-an-environment","level":2,"title":"Verifying an environment","text":"It is possible to install packages with conflicting requirements into an environment if installed in multiple steps.
To check for conflicts or missing dependencies in the environment:
$ uv pip check\n
","path":["Concepts","The pip interface","Inspecting environments"],"tags":[]},{"location":"pip/packages/","level":1,"title":"Managing packages","text":"","path":["Concepts","The pip interface","Managing packages"],"tags":[]},{"location":"pip/packages/#installing-a-package","level":2,"title":"Installing a package","text":"To install a package into the virtual environment, e.g., Flask:
$ uv pip install flask\n
To install a package with optional dependencies enabled, e.g., Flask with the \"dotenv\" extra:
$ uv pip install \"flask[dotenv]\"\n
To install multiple packages, e.g., Flask and Ruff:
$ uv pip install flask ruff\n
To install a package with a constraint, e.g., Ruff v0.2.0 or newer:
$ uv pip install 'ruff>=0.2.0'\n
To install a package at a specific version, e.g., Ruff v0.3.0:
$ uv pip install 'ruff==0.3.0'\n
To install a package from the disk:
$ uv pip install \"ruff @ ./projects/ruff\"\n
To install a package from GitHub:
$ uv pip install \"git+https://github.com/astral-sh/ruff\"\n
To install a package from GitHub at a specific reference:
$ # Install a tag\n$ uv pip install \"git+https://github.com/astral-sh/ruff@v0.2.0\"\n\n$ # Install a commit\n$ uv pip install \"git+https://github.com/astral-sh/ruff@1fadefa67b26508cc59cf38e6130bde2243c929d\"\n\n$ # Install a branch\n$ uv pip install \"git+https://github.com/astral-sh/ruff@main\"\n
See the Git authentication documentation for installation from a private repository.
","path":["Concepts","The pip interface","Managing packages"],"tags":[]},{"location":"pip/packages/#editable-packages","level":2,"title":"Editable packages","text":"Editable packages do not need to be reinstalled for changes to their source code to be active.
To install the current project as an editable package
$ uv pip install -e .\n
To install a project in another directory as an editable package:
$ uv pip install -e \"ruff @ ./project/ruff\"\n
","path":["Concepts","The pip interface","Managing packages"],"tags":[]},{"location":"pip/packages/#installing-packages-from-files","level":2,"title":"Installing packages from files","text":"Multiple packages can be installed at once from standard file formats.
Install from a requirements.txt file:
$ uv pip install -r requirements.txt\n
See the uv pip compile documentation for more information on requirements.txt files.
Install from a pyproject.toml file:
$ uv pip install -r pyproject.toml\n
Install from a pyproject.toml file with optional dependencies enabled, e.g., the \"foo\" extra:
$ uv pip install -r pyproject.toml --extra foo\n
Install from a pyproject.toml file with all optional dependencies enabled:
$ uv pip install -r pyproject.toml --all-extras\n
To install dependency groups in the current project directory's pyproject.toml, for example the group foo:
$ uv pip install --group foo\n
To specify the project directory where groups should be sourced from:
$ uv pip install --project some/path/ --group foo --group bar\n
Alternatively, you can specify a path to a pyproject.toml for each group:
$ uv pip install --group some/path/pyproject.toml:foo --group other/pyproject.toml:bar\n
Note
As in pip, --group flags do not apply to other sources specified with flags like -r or -e. For instance, uv pip install -r some/path/pyproject.toml --group foo sources foo from ./pyproject.toml and not some/path/pyproject.toml.
","path":["Concepts","The pip interface","Managing packages"],"tags":[]},{"location":"pip/packages/#uninstalling-a-package","level":2,"title":"Uninstalling a package","text":"To uninstall a package, e.g., Flask:
$ uv pip uninstall flask\n
To uninstall multiple packages, e.g., Flask and Ruff:
$ uv pip uninstall flask ruff\n
","path":["Concepts","The pip interface","Managing packages"],"tags":[]},{"location":"reference/","level":1,"title":"Reference","text":"The reference section provides information about specific parts of uv:
- Commands: A reference for uv's command line interface.
- Settings: A reference for uv's configuration schema.
- Resolver: Details about the internals of uv's resolver.
- Policies: uv's versioning policy, platform support policy, and license.
Looking for a broader overview? Check out the concepts documentation.
","path":["Reference"],"tags":[]},{"location":"reference/benchmarks/","level":1,"title":"Benchmarks","text":"uv's performance is continually benchmarked against previous releases, and regularly compared to other tools in the space, like pip and Poetry.
The latest benchmarks and details on the benchmarking process can be found in the GitHub repository.
","path":["Reference","Benchmarks"],"tags":[]},{"location":"reference/cli/","level":1,"title":"CLI Reference","text":"","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv","level":2,"title":"uv","text":"An extremely fast Python package manager.
Usage uv [OPTIONS] <COMMAND>\n
Commands uv authManage authentication
uv runRun a command or script
uv initCreate a new project
uv addAdd dependencies to the project
uv removeRemove dependencies from the project
uv versionRead or update the project's version
uv syncUpdate the project's environment
uv lockUpdate the project's lockfile
uv exportExport the project's lockfile to an alternate format
uv treeDisplay the project's dependency tree
uv formatFormat Python code in the project
uv toolRun and install commands provided by Python packages
uv pythonManage Python versions and installations
uv pipManage Python packages with a pip-compatible interface
uv venvCreate a virtual environment
uv buildBuild Python packages into source distributions and wheels
uv publishUpload distributions to an index
uv cacheManage uv's cache
uv selfManage the uv executable
uv helpDisplay documentation for a command
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-auth","level":2,"title":"uv auth","text":"Manage authentication
Usage uv auth [OPTIONS] <COMMAND>\n
Commands uv auth loginLogin to a service
uv auth logoutLogout of a service
uv auth tokenShow the authentication token for a service
uv auth dirShow the path to the uv credentials directory
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-auth-login","level":3,"title":"uv auth loginUsageArgumentsOptions","text":"Login to a service
uv auth login [OPTIONS] <SERVICE>\n
SERVICEThe domain or URL of the service to log into
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--keyring-provider keyring-providerThe keyring provider to use for storage of credentials.
Only --keyring-provider native is supported for login, which uses the system keyring via an integration built into uv.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--password passwordThe password to use for the service.
Use - to read the password from stdin.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--token, -t tokenThe token to use for the service.
The username will be set to __token__.
Use - to read the token from stdin.
--username, -u usernameThe username to use for the service
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-auth-logout","level":3,"title":"uv auth logoutUsageArgumentsOptions","text":"Logout of a service
uv auth logout [OPTIONS] <SERVICE>\n
SERVICEThe domain or URL of the service to logout from
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--keyring-provider keyring-providerThe keyring provider to use for storage of credentials.
Only --keyring-provider native is supported for logout, which uses the system keyring via an integration built into uv.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--username, -u usernameThe username to logout
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-auth-token","level":3,"title":"uv auth tokenUsageArgumentsOptions","text":"Show the authentication token for a service
uv auth token [OPTIONS] <SERVICE>\n
SERVICEThe domain or URL of the service to lookup
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--keyring-provider keyring-providerThe keyring provider to use for reading credentials
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--username, -u usernameThe username to lookup
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-auth-dir","level":3,"title":"uv auth dirUsageArgumentsOptions","text":"Show the path to the uv credentials directory.
By default, credentials are stored in the uv data directory at $XDG_DATA_HOME/uv/credentials or $HOME/.local/share/uv/credentials on Unix and %APPDATA%\\uv\\data\\credentials on Windows.
The credentials directory may be overridden with $UV_CREDENTIALS_DIR.
Credentials are only stored in this directory when the plaintext backend is used, as opposed to the native backend, which uses the system keyring.
uv auth dir [OPTIONS] [SERVICE]\n
SERVICEThe domain or URL of the service to lookup
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-run","level":2,"title":"uv run","text":"Run a command or script.
Ensures that the command runs in a Python environment.
When used with a file ending in .py or an HTTP(S) URL, the file will be treated as a script and run with a Python interpreter, i.e., uv run file.py is equivalent to uv run python file.py. For URLs, the script is temporarily downloaded before execution. If the script contains inline dependency metadata, it will be installed into an isolated, ephemeral environment. When used with -, the input will be read from stdin, and treated as a Python script.
When used in a project, the project environment will be created and updated before invoking the command.
When used outside a project, if a virtual environment can be found in the current directory or a parent directory, the command will be run in that environment. Otherwise, the command will be run in the environment of the discovered interpreter.
Arguments following the command (or script) are not interpreted as arguments to uv. All options to uv must be provided before the command, e.g., uv run --verbose foo. A -- can be used to separate the command from uv options for clarity, e.g., uv run --python 3.12 -- python.
Usage uv run [OPTIONS] [COMMAND]\n
Options --activePrefer the active virtual environment over the project's virtual environment.
If the project virtual environment is active or no virtual environment is active, this has no effect.
--all-extrasInclude all optional dependencies.
Optional dependencies are defined via project.optional-dependencies in a pyproject.toml.
This option is only available when running in a project.
--all-groupsInclude dependencies from all dependency groups.
--no-group can be used to exclude specific groups.
--all-packagesRun the command with all workspace members installed.
The workspace's environment (.venv) is updated to include all workspace members.
Any extras or groups specified via --extra, --group, or related options will be applied to all workspace members.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--env-file env-fileLoad environment variables from a .env file.
Can be provided multiple times, with subsequent files overriding values defined in previous files.
May also be set with the UV_ENV_FILE environment variable.
--exactPerform an exact sync, removing extraneous packages.
When enabled, uv will remove any extraneous packages from the environment. By default, uv run will make the minimum necessary changes to satisfy the requirements.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--extra extraInclude optional dependencies from the specified extra name.
May be provided more than once.
Optional dependencies are defined via project.optional-dependencies in a pyproject.toml.
This option is only available when running in a project.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--frozenRun without updating the uv.lock file.
Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the pyproject.toml includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.
May also be set with the UV_FROZEN environment variable.
--group groupInclude dependencies from the specified dependency group.
May be provided multiple times.
--gui-scriptRun the given path as a Python GUI script.
Using --gui-script will attempt to parse the path as a PEP 723 script and run it with pythonw.exe, irrespective of its extension. Only available on Windows.
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--isolatedRun the command in an isolated virtual environment.
Usually, the project environment is reused for performance. This option forces a fresh environment to be used for the project, enforcing strict isolation between dependencies and declaration of requirements.
An editable installation is still used for the project.
When used with --with or --with-requirements, the additional dependencies will still be layered in a second environment.
May also be set with the UV_ISOLATED environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--lockedAssert that the uv.lock will remain unchanged.
Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
May also be set with the UV_LOCKED environment variable.
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--module, -mRun a Python module.
Equivalent to python -m <module>.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
--no-build-package no-build-packageDon't build source distributions for a specific package
May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-default-groupsIgnore the default dependency groups.
uv includes the groups defined in tool.uv.default-groups by default. This disables that option, however, specific groups can still be included with --group.
--no-devDisable the development dependency group.
This option is an alias of --no-group dev. See --no-default-groups to disable all default groups instead.
This option is only available when running in a project.
May also be set with the UV_NO_DEV environment variable.
--no-editableInstall any editable dependencies, including the project and any workspace members, as non-editable
May also be set with the UV_NO_EDITABLE environment variable.
--no-env-fileAvoid reading environment variables from a .env file
May also be set with the UV_NO_ENV_FILE environment variable.
--no-extra no-extraExclude the specified optional dependencies, if --all-extras is supplied.
May be provided multiple times.
--no-group no-groupDisable the specified dependency group.
This option always takes precedence over default groups, --all-groups, and --group.
May be provided multiple times.
May also be set with the UV_NO_GROUP environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-project, --no_workspaceAvoid discovering the project or workspace.
Instead of searching for projects in the current directory and parent directories, run in an isolated, ephemeral environment populated by the --with requirements.
If a virtual environment is active or found in a current or parent directory, it will be used as if there was no project or workspace.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--no-syncAvoid syncing the virtual environment.
Implies --frozen, as the project dependencies will be ignored (i.e., the lockfile will not be updated, since the environment will not be synced regardless).
May also be set with the UV_NO_SYNC environment variable.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--only-devOnly include the development dependency group.
The project and its dependencies will be omitted.
This option is an alias for --only-group dev. Implies --no-default-groups.
--only-group only-groupOnly include dependencies from the specified dependency group.
The project and its dependencies will be omitted.
May be provided multiple times. Implies --no-default-groups.
--package packageRun the command in a specific package in the workspace.
If the workspace member does not exist, uv will exit with an error.
--prerelease prereleaseThe 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).
May also be set with the UV_PRERELEASE environment variable.
Possible values:
disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use for the run environment.
If the interpreter request is satisfied by a discovered environment, the environment will be used.
See uv python to view supported request formats.
May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which requirements should be installed.
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.
When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.
Possible values:
windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--refreshRefresh all cached data
--refresh-package refresh-packageRefresh cached data for a specific package
--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
--resolution resolutionThe 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).
May also be set with the UV_RESOLUTION environment variable.
Possible values:
highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script, -sRun the given path as a Python script.
Using --script will attempt to parse the path as a PEP 723 script, irrespective of its extension.
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
--with, -w withRun with the given packages installed.
When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.
--with-editable with-editableRun with the given packages installed in editable mode.
When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.
--with-requirements with-requirementsRun with the packages listed in the given files.
The following formats are supported: requirements.txt, .py files with inline metadata, and pylock.toml.
The same environment semantics as --with apply.
Using pyproject.toml, setup.py, or setup.cfg files is not allowed.
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-init","level":2,"title":"uv init","text":"Create a new project.
Follows the pyproject.toml specification.
If a pyproject.toml already exists at the target, uv will exit with an error.
If a pyproject.toml is found in any of the parent directories of the target path, the project will be added as a workspace member of the parent.
Some project state is not created until needed, e.g., the project virtual environment (.venv) and lockfile (uv.lock) are lazily created during the first sync.
Usage uv init [OPTIONS] [PATH]\n
Arguments PATHThe path to use for the project/script.
Defaults to the current working directory when initializing an app or library; required when initializing a script. Accepts relative and absolute paths.
If a pyproject.toml is found in any of the parent directories of the target path, the project will be added as a workspace member of the parent, unless --no-workspace is provided.
Options --allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--app, --applicationCreate a project for an application.
This is the default behavior if --lib is not requested.
This project kind is for web servers, scripts, and command-line interfaces.
By default, an application is not intended to be built and distributed as a Python package. The --package option can be used to create an application that is distributable, e.g., if you want to distribute a command-line interface via PyPI.
--author-from author-fromFill in the authors field in the pyproject.toml.
By default, uv will attempt to infer the author information from some sources (e.g., Git) (auto). Use --author-from git to only infer from Git configuration. Use --author-from none to avoid inferring the author information.
Possible values:
auto: Fetch the author information from some sources (e.g., Git) automaticallygit: Fetch the author information from Git configuration onlynone: Do not infer the author information
--bareOnly create a pyproject.toml.
Disables creating extra files like README.md, the src/ tree, .python-version files, etc.
--build-backend build-backendInitialize a build-backend of choice for the project.
Implicitly sets --package.
May also be set with the UV_INIT_BUILD_BACKEND environment variable.
Possible values:
uv: Use uv as the project build backendhatch: Use hatchling as the project build backendflit: Use flit-core as the project build backendpdm: Use pdm-backend as the project build backendpoetry: Use poetry-core as the project build backendsetuptools: Use setuptools as the project build backendmaturin: Use maturin as the project build backendscikit: Use scikit-build-core as the project build backend
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--description descriptionSet the project description
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--lib, --libraryCreate a project for a library.
A library is a project that is intended to be built and distributed as a Python package.
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--name nameThe name of the project.
Defaults to the name of the directory.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-descriptionDisable the description for the project
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-packageDo not set up the project to be built as a Python package.
Does not include a [build-system] for the project.
This is the default behavior when using --app.
--no-pin-pythonDo not create a .python-version file for the project.
By default, uv will create a .python-version file containing the minor version of the discovered Python interpreter, which will cause subsequent uv commands to use that version.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-readmeDo not create a README.md file
--no-workspace, --no-projectAvoid discovering a workspace and create a standalone project.
By default, uv searches for workspaces in the current directory or any parent directory.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--packageSet up the project to be built as a Python package.
Defines a [build-system] for the project.
This is the default behavior when using --lib or --build-backend.
When using --app, this will include a [project.scripts] entrypoint and use a src/ project structure.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use to determine the minimum supported Python version.
See uv python to view supported request formats.
May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--scriptCreate a script.
A script is a standalone file with embedded metadata enumerating its dependencies, along with any Python version requirements, as defined in the PEP 723 specification.
PEP 723 scripts can be executed directly with uv run.
By default, adds a requirement on the system Python version; use --python to specify an alternative Python version requirement.
--vcs vcsInitialize a version control system for the project.
By default, uv will initialize a Git repository (git). Use --vcs none to explicitly avoid initializing a version control system.
Possible values:
git: Use Git for version controlnone: Do not use any version control system
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-add","level":2,"title":"uv add","text":"Add dependencies to the project.
Dependencies are added to the project's pyproject.toml file.
If a given dependency exists already, it will be updated to the new version specifier unless it includes markers that differ from the existing specifier in which case another entry for the dependency will be added.
The lockfile and project environment will be updated to reflect the added dependencies. To skip updating the lockfile, use --frozen. To skip updating the environment, use --no-sync.
If any of the requested dependencies cannot be found, uv will exit with an error, unless the --frozen flag is provided, in which case uv will add the dependencies verbatim without checking that they exist or are compatible with the project.
uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.
Usage uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>\n
Arguments PACKAGESThe packages to add, as PEP 508 requirements (e.g., ruff==0.5.0)
Options --activePrefer the active virtual environment over the project's virtual environment.
If the project virtual environment is active or no virtual environment is active, this has no effect.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--bounds boundsThe kind of version specifier to use when adding dependencies.
When adding a dependency to the project, if no constraint or URL is provided, a constraint is added based on the latest compatible version of the package. By default, a lower bound constraint is used, e.g., >=1.2.3.
When --frozen is provided, no resolution is performed, and dependencies are always added without constraints.
This option is in preview and may change in any future release.
Possible values:
lower: Only a lower bound, e.g., >=1.2.3major: Allow the same major version, similar to the semver caret, e.g., >=1.2.3, <2.0.0minor: Allow the same minor version, similar to the semver tilde, e.g., >=1.2.3, <1.3.0exact: Pin the exact version, e.g., ==1.2.3
--branch branchBranch to use when adding a dependency from Git
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--constraints, --constraint, -c constraintsConstrain versions using the given requirements files.
Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. The constraints will not be added to the project's pyproject.toml file, but will be respected during dependency resolution.
This is equivalent to pip's --constraint option.
May also be set with the UV_CONSTRAINT environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--devAdd the requirements to the development dependency group.
This option is an alias for --group dev.
May also be set with the UV_DEV environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--editableAdd the requirements as editable
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--extra extraExtras to enable for the dependency.
May be provided more than once.
To add this dependency to an optional extra instead, see --optional.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--frozenAdd dependencies without re-locking the project.
The project environment will not be synced.
May also be set with the UV_FROZEN environment variable.
--group groupAdd the requirements to the specified dependency group.
These requirements will not be included in the published metadata for the project.
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--lockedAssert that the uv.lock will remain unchanged.
Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
May also be set with the UV_LOCKED environment variable.
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--marker, -m markerApply this marker to all added packages
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
--no-build-package no-build-packageDon't build source distributions for a specific package
May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-install-localDo not install local path dependencies
Skips the current project, workspace members, and any other local (path or editable) packages. Only remote/indexed dependencies are installed. Useful in Docker builds to cache heavy third-party dependencies first and layer local packages separately.
--no-install-projectDo not install the current project.
By default, the current project is installed into the environment with all of its dependencies. The --no-install-project option allows the project to be excluded, but all of its dependencies are still installed. This is particularly useful in situations like building Docker images where installing the project separately from its dependencies allows optimal layer caching.
--no-install-workspaceDo not install any workspace members, including the current project.
By default, all of the workspace members and their dependencies are installed into the environment. The --no-install-workspace option allows exclusion of all the workspace members while retaining their dependencies. This is particularly useful in situations like building Docker images where installing the workspace separately from its dependencies allows optimal layer caching.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--no-syncAvoid syncing the virtual environment
May also be set with the UV_NO_SYNC environment variable.
--no-workspaceDon't add the dependency as a workspace member.
By default, when adding a dependency that's a local path and is within the workspace directory, uv will add it as a workspace member; pass --no-workspace to add the package as direct path dependency instead.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--optional optionalAdd the requirements to the package's optional dependencies for the specified extra.
The group may then be activated when installing the project with the --extra flag.
To enable an optional extra for this requirement instead, see --extra.
--package packageAdd the dependency to a specific package in the workspace
--prerelease prereleaseThe 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).
May also be set with the UV_PRERELEASE environment variable.
Possible values:
disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use for resolving and syncing.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--raw, --raw-sourcesAdd a dependency as provided.
By default, uv will use the tool.uv.sources section to record source information for Git, local, editable, and direct URL requirements. When --raw is provided, uv will add source requirements to project.dependencies, rather than tool.uv.sources.
Additionally, by default, uv will add bounds to your dependency, e.g., foo>=1.0.0. When --raw is provided, uv will add the dependency without bounds.
--refreshRefresh all cached data
--refresh-package refresh-packageRefresh cached data for a specific package
--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
--requirements, --requirement, -r requirementsAdd the packages listed in the given files.
The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.
--resolution resolutionThe 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).
May also be set with the UV_RESOLUTION environment variable.
Possible values:
highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--rev revCommit to use when adding a dependency from Git
--script scriptAdd the dependency to the specified Python script, rather than to a project.
If provided, uv will add the dependency to the script's inline metadata table, in adherence with PEP 723. If no such inline metadata table is present, a new one will be created and added to the script. When executed via uv run, uv will create a temporary environment for the script with all inline dependencies installed.
--tag tagTag to use when adding a dependency from Git
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
--workspaceAdd the dependency as a workspace member.
By default, uv will add path dependencies that are within the workspace directory as workspace members. When used with a path dependency, the package will be added to the workspace's members list in the root pyproject.toml file.
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-remove","level":2,"title":"uv remove","text":"Remove dependencies from the project.
Dependencies are removed from the project's pyproject.toml file.
If multiple entries exist for a given dependency, i.e., each with different markers, all of the entries will be removed.
The lockfile and project environment will be updated to reflect the removed dependencies. To skip updating the lockfile, use --frozen. To skip updating the environment, use --no-sync.
If any of the requested dependencies are not present in the project, uv will exit with an error.
If a package has been manually installed in the environment, i.e., with uv pip install, it will not be removed by uv remove.
uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.
Usage uv remove [OPTIONS] <PACKAGES>...\n
Arguments PACKAGESThe names of the dependencies to remove (e.g., ruff)
Options --activePrefer the active virtual environment over the project's virtual environment.
If the project virtual environment is active or no virtual environment is active, this has no effect.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--devRemove the packages from the development dependency group.
This option is an alias for --group dev.
May also be set with the UV_DEV environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--frozenRemove dependencies without re-locking the project.
The project environment will not be synced.
May also be set with the UV_FROZEN environment variable.
--group groupRemove the packages from the specified dependency group
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--lockedAssert that the uv.lock will remain unchanged.
Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
May also be set with the UV_LOCKED environment variable.
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
--no-build-package no-build-packageDon't build source distributions for a specific package
May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--no-syncAvoid syncing the virtual environment after re-locking the project
May also be set with the UV_NO_SYNC environment variable.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--optional optionalRemove the packages from the project's optional dependencies for the specified extra
--package packageRemove the dependencies from a specific package in the workspace
--prerelease prereleaseThe 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).
May also be set with the UV_PRERELEASE environment variable.
Possible values:
disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use for resolving and syncing.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--refreshRefresh all cached data
--refresh-package refresh-packageRefresh cached data for a specific package
--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
--resolution resolutionThe 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).
May also be set with the UV_RESOLUTION environment variable.
Possible values:
highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script scriptRemove the dependency from the specified Python script, rather than from a project.
If provided, uv will remove the dependency from the script's inline metadata table, in adherence with PEP 723.
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-version","level":2,"title":"uv version","text":"Read or update the project's version
Usage uv version [OPTIONS] [VALUE]\n
Arguments VALUESet the project version to this value
To update the project using semantic versioning components instead, use --bump.
Options --activePrefer the active virtual environment over the project's virtual environment.
If the project virtual environment is active or no virtual environment is active, this has no effect.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--bump bumpUpdate the project version using the given semantics
This flag can be passed multiple times.
Possible values:
major: Increase the major version (e.g., 1.2.3 => 2.0.0)minor: Increase the minor version (e.g., 1.2.3 => 1.3.0)patch: Increase the patch version (e.g., 1.2.3 => 1.2.4)stable: Move from a pre-release to stable version (e.g., 1.2.3b4.post5.dev6 => 1.2.3)alpha: Increase the alpha version (e.g., 1.2.3a4 => 1.2.3a5)beta: Increase the beta version (e.g., 1.2.3b4 => 1.2.3b5)rc: Increase the rc version (e.g., 1.2.3rc4 => 1.2.3rc5)post: Increase the post version (e.g., 1.2.3.post5 => 1.2.3.post6)dev: Increase the dev version (e.g., 1.2.3a4.dev6 => 1.2.3.dev7)
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runDon't write a new version to the pyproject.toml
Instead, the version will be displayed.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--frozenUpdate the version without re-locking the project.
The project environment will not be synced.
May also be set with the UV_FROZEN environment variable.
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--lockedAssert that the uv.lock will remain unchanged.
Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
May also be set with the UV_LOCKED environment variable.
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
--no-build-package no-build-packageDon't build source distributions for a specific package
May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--no-syncAvoid syncing the virtual environment after re-locking the project
May also be set with the UV_NO_SYNC environment variable.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--output-format output-formatThe format of the output
[default: text]
Possible values:
text: Display the version as plain textjson: Display the version as JSON
--package packageUpdate the version of a specific package in the workspace
--prerelease prereleaseThe 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).
May also be set with the UV_PRERELEASE environment variable.
Possible values:
disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use for resolving and syncing.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--refreshRefresh all cached data
--refresh-package refresh-packageRefresh cached data for a specific package
--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
--resolution resolutionThe 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).
May also be set with the UV_RESOLUTION environment variable.
Possible values:
highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--shortOnly show the version
By default, uv will show the project name before the version.
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-sync","level":2,"title":"uv sync","text":"Update the project's environment.
Syncing ensures that all project dependencies are installed and up-to-date with the lockfile.
By default, an exact sync is performed: uv removes packages that are not declared as dependencies of the project. Use the --inexact flag to keep extraneous packages. Note that if an extraneous package conflicts with a project dependency, it will still be removed. Additionally, if --no-build-isolation is used, uv will not remove extraneous packages to avoid removing possible build dependencies.
If the project virtual environment (.venv) does not exist, it will be created.
The project is re-locked before syncing unless the --locked or --frozen flag is provided.
uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.
Note that, when installing from a lockfile, uv will not provide warnings for yanked package versions.
Usage uv sync [OPTIONS]\n
Options --activeSync dependencies to the active virtual environment.
Instead of creating or updating the virtual environment for the project or script, the active virtual environment will be preferred, if the VIRTUAL_ENV environment variable is set.
--all-extrasInclude all optional dependencies.
When two or more extras are declared as conflicting in tool.uv.conflicts, using this flag will always result in an error.
Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.
--all-groupsInclude dependencies from all dependency groups.
--no-group can be used to exclude specific groups.
--all-packagesSync all packages in the workspace.
The workspace's environment (.venv) is updated to include all workspace members.
Any extras or groups specified via --extra, --group, or related options will be applied to all workspace members.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--checkCheck if the Python environment is synchronized with the project.
If the environment is not up to date, uv will exit with an error.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runPerform a dry run, without writing the lockfile or modifying the project environment.
In dry-run mode, uv will resolve the project's dependencies and report on the resulting changes to both the lockfile and the project environment, but will not modify either.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--extra extraInclude optional dependencies from the specified extra name.
May be provided more than once.
When multiple extras or groups are specified that appear in tool.uv.conflicts, uv will report an error.
Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--frozenSync without updating the uv.lock file.
Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the pyproject.toml includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.
May also be set with the UV_FROZEN environment variable.
--group groupInclude dependencies from the specified dependency group.
When multiple extras or groups are specified that appear in tool.uv.conflicts, uv will report an error.
May be provided multiple times.
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--inexact, --no-exactDo not remove extraneous packages present in the environment.
When enabled, uv will make the minimum necessary changes to satisfy the requirements. By default, syncing will remove any extraneous packages from the environment
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--lockedAssert that the uv.lock will remain unchanged.
Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
May also be set with the UV_LOCKED environment variable.
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
--no-build-package no-build-packageDon't build source distributions for a specific package
May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-default-groupsIgnore the default dependency groups.
uv includes the groups defined in tool.uv.default-groups by default. This disables that option, however, specific groups can still be included with --group.
--no-devDisable the development dependency group.
This option is an alias of --no-group dev. See --no-default-groups to disable all default groups instead.
May also be set with the UV_NO_DEV environment variable.
--no-editableInstall any editable dependencies, including the project and any workspace members, as non-editable
May also be set with the UV_NO_EDITABLE environment variable.
--no-extra no-extraExclude the specified optional dependencies, if --all-extras is supplied.
May be provided multiple times.
--no-group no-groupDisable the specified dependency group.
This option always takes precedence over default groups, --all-groups, and --group.
May be provided multiple times.
May also be set with the UV_NO_GROUP environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-install-localDo not install local path dependencies
Skips the current project, workspace members, and any other local (path or editable) packages. Only remote/indexed dependencies are installed. Useful in Docker builds to cache heavy third-party dependencies first and layer local packages separately.
--no-install-package no-install-packageDo not install the given package(s).
By default, all of the project's dependencies are installed into the environment. The --no-install-package option allows exclusion of specific packages. Note this can result in a broken environment, and should be used with caution.
--no-install-projectDo not install the current project.
By default, the current project is installed into the environment with all of its dependencies. The --no-install-project option allows the project to be excluded, but all of its dependencies are still installed. This is particularly useful in situations like building Docker images where installing the project separately from its dependencies allows optimal layer caching.
--no-install-workspaceDo not install any workspace members, including the root project.
By default, all of the workspace members and their dependencies are installed into the environment. The --no-install-workspace option allows exclusion of all the workspace members while retaining their dependencies. This is particularly useful in situations like building Docker images where installing the workspace separately from its dependencies allows optimal layer caching.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--only-devOnly include the development dependency group.
The project and its dependencies will be omitted.
This option is an alias for --only-group dev. Implies --no-default-groups.
--only-group only-groupOnly include dependencies from the specified dependency group.
The project and its dependencies will be omitted.
May be provided multiple times. Implies --no-default-groups.
--output-format output-formatSelect the output format
[default: text]
Possible values:
text: Display the result in a human-readable formatjson: Display the result in JSON format
--package packageSync for specific packages in the workspace.
The workspace's environment (.venv) is updated to reflect the subset of dependencies declared by the specified workspace member packages.
If any workspace member does not exist, uv will exit with an error.
--prerelease prereleaseThe 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).
May also be set with the UV_PRERELEASE environment variable.
Possible values:
disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use for the project environment.
By default, the first interpreter that meets the project's requires-python constraint is used.
If a Python interpreter in a virtual environment is provided, the packages will not be synced to the given environment. The interpreter will be used to create a virtual environment in the project.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which requirements should be installed.
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.
When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.
Possible values:
windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--refreshRefresh all cached data
--refresh-package refresh-packageRefresh cached data for a specific package
--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
--resolution resolutionThe 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).
May also be set with the UV_RESOLUTION environment variable.
Possible values:
highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script scriptSync the environment for a Python script, rather than the current project.
If provided, uv will sync the dependencies based on the script's inline metadata table, in adherence with PEP 723.
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-lock","level":2,"title":"uv lock","text":"Update the project's lockfile.
If the project lockfile (uv.lock) does not exist, it will be created. If a lockfile is present, its contents will be used as preferences for the resolution.
If there are no changes to the project's dependencies, locking will have no effect unless the --upgrade flag is provided.
Usage uv lock [OPTIONS]\n
Options --allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--checkCheck if the lockfile is up-to-date.
Asserts that the uv.lock would remain unchanged after a resolution. If the lockfile is missing or needs to be updated, uv will exit with an error.
Equivalent to --locked.
--check-exists, --frozenAssert that a uv.lock exists without checking if it is up-to-date.
Equivalent to --frozen.
May also be set with the UV_FROZEN environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runPerform a dry run, without writing the lockfile.
In dry-run mode, uv will resolve the project's dependencies and report on the resulting changes, but will not write the lockfile to disk.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for a specific package to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
This option is only used when building source distributions.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
--no-build-package no-build-packageDon't build source distributions for a specific package
May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--prerelease prereleaseThe 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).
May also be set with the UV_PRERELEASE environment variable.
Possible values:
disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use during resolution.
A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.
The interpreter is also used as the fallback value for the minimum Python version if requires-python is not set.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--refreshRefresh all cached data
--refresh-package refresh-packageRefresh cached data for a specific package
--resolution resolutionThe 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).
May also be set with the UV_RESOLUTION environment variable.
Possible values:
highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script scriptLock the specified Python script, rather than the current project.
If provided, uv will lock the script (based on its inline metadata table, in adherence with PEP 723) to a .lock file adjacent to the script itself.
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-export","level":2,"title":"uv export","text":"Export the project's lockfile to an alternate format.
At present, both requirements.txt and pylock.toml (PEP 751) formats are supported.
The project is re-locked before exporting unless the --locked or --frozen flag is provided.
uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.
If operating in a workspace, the root will be exported by default; however, specific members can be selected using the --package option.
Usage uv export [OPTIONS]\n
Options --all-extrasInclude all optional dependencies
--all-groupsInclude dependencies from all dependency groups.
--no-group can be used to exclude specific groups.
--all-packagesExport the entire workspace.
The dependencies for all workspace members will be included in the exported requirements file.
Any extras or groups specified via --extra, --group, or related options will be applied to all workspace members.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for a specific package to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--extra extraInclude optional dependencies from the specified extra name.
May be provided more than once.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--format formatThe format to which uv.lock should be exported.
Supports both requirements.txt and pylock.toml (PEP 751) output formats.
uv will infer the output format from the file extension of the output file, if provided. Otherwise, defaults to requirements.txt.
Possible values:
requirements.txt: Export in requirements.txt formatpylock.toml: Export in pylock.toml format
--frozenDo not update the uv.lock before exporting.
If a uv.lock does not exist, uv will exit with an error.
May also be set with the UV_FROZEN environment variable.
--group groupInclude dependencies from the specified dependency group.
May be provided multiple times.
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
This option is only used when building source distributions.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--lockedAssert that the uv.lock will remain unchanged.
Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
May also be set with the UV_LOCKED environment variable.
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-annotateExclude comment annotations indicating the source of each package
--no-binaryDon'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.
May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
--no-build-package no-build-packageDon't build source distributions for a specific package
May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-default-groupsIgnore the default dependency groups.
uv includes the groups defined in tool.uv.default-groups by default. This disables that option, however, specific groups can still be included with --group.
--no-devDisable the development dependency group.
This option is an alias of --no-group dev. See --no-default-groups to disable all default groups instead.
May also be set with the UV_NO_DEV environment variable.
--no-editableExport any editable dependencies, including the project and any workspace members, as non-editable
May also be set with the UV_NO_EDITABLE environment variable.
--no-emit-local, --no-install-localDo not include local path dependencies in the exported requirements.
Omits the current project, workspace members, and any other local (path or editable) packages from the export. Only remote/indexed dependencies are written. Useful for Docker and CI flows that want to export and cache third-party dependencies first.
--no-emit-package, --no-install-package no-emit-packageDo not emit the given package(s).
By default, all of the project's dependencies are included in the exported requirements file. The --no-emit-package option allows exclusion of specific packages.
--no-emit-project, --no-install-projectDo not emit the current project.
By default, the current project is included in the exported requirements file with all of its dependencies. The --no-emit-project option allows the project to be excluded, but all of its dependencies to remain included.
--no-emit-workspace, --no-install-workspaceDo not emit any workspace members, including the root project.
By default, all workspace members and their dependencies are included in the exported requirements file, with all of their dependencies. The --no-emit-workspace option allows exclusion of all the workspace members while retaining their dependencies.
--no-extra no-extraExclude the specified optional dependencies, if --all-extras is supplied.
May be provided multiple times.
--no-group no-groupDisable the specified dependency group.
This option always takes precedence over default groups, --all-groups, and --group.
May be provided multiple times.
May also be set with the UV_NO_GROUP environment variable.
--no-hashesOmit hashes in the generated output
--no-headerExclude the comment header at the top of the generated output file
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--only-devOnly include the development dependency group.
The project and its dependencies will be omitted.
This option is an alias for --only-group dev. Implies --no-default-groups.
--only-group only-groupOnly include dependencies from the specified dependency group.
The project and its dependencies will be omitted.
May be provided multiple times. Implies --no-default-groups.
--output-file, -o output-fileWrite the exported requirements to the given file
--package packageExport the dependencies for specific packages in the workspace.
If any workspace member does not exist, uv will exit with an error.
--prerelease prereleaseThe 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).
May also be set with the UV_PRERELEASE environment variable.
Possible values:
disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--prune packagePrune the given package from the dependency tree.
Pruned packages will be excluded from the exported requirements file, as will any dependencies that are no longer required after the pruned package is removed.
--python, -p pythonThe Python interpreter to use during resolution.
A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.
The interpreter is also used as the fallback value for the minimum Python version if requires-python is not set.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--refreshRefresh all cached data
--refresh-package refresh-packageRefresh cached data for a specific package
--resolution resolutionThe 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).
May also be set with the UV_RESOLUTION environment variable.
Possible values:
highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script scriptExport the dependencies for the specified PEP 723 Python script, rather than the current project.
If provided, uv will resolve the dependencies based on its inline metadata table, in adherence with PEP 723.
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-tree","level":2,"title":"uv tree","text":"Display the project's dependency tree
Usage uv tree [OPTIONS]\n
Options --all-groupsInclude dependencies from all dependency groups.
--no-group can be used to exclude specific groups.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--depth, -d depthMaximum display depth of the dependency tree
[default: 255]
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for a specific package to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--frozenDisplay the requirements without locking the project.
If the lockfile is missing, uv will exit with an error.
May also be set with the UV_FROZEN environment variable.
--group groupInclude dependencies from the specified dependency group.
May be provided multiple times.
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--invert, --reverseShow the reverse dependencies for the given package. This flag will invert the tree and display the packages that depend on the given package
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
This option is only used when building source distributions.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--lockedAssert that the uv.lock will remain unchanged.
Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.
May also be set with the UV_LOCKED environment variable.
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
--no-build-package no-build-packageDon't build source distributions for a specific package
May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-dedupeDo not de-duplicate repeated dependencies. Usually, when a package has already displayed its dependencies, further occurrences will not re-display its dependencies, and will include a (*) to indicate it has already been shown. This flag will cause those duplicates to be repeated
--no-default-groupsIgnore the default dependency groups.
uv includes the groups defined in tool.uv.default-groups by default. This disables that option, however, specific groups can still be included with --group.
--no-devDisable the development dependency group.
This option is an alias of --no-group dev. See --no-default-groups to disable all default groups instead.
May also be set with the UV_NO_DEV environment variable.
--no-group no-groupDisable the specified dependency group.
This option always takes precedence over default groups, --all-groups, and --group.
May be provided multiple times.
May also be set with the UV_NO_GROUP environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--only-devOnly include the development dependency group.
The project and its dependencies will be omitted.
This option is an alias for --only-group dev. Implies --no-default-groups.
--only-group only-groupOnly include dependencies from the specified dependency group.
The project and its dependencies will be omitted.
May be provided multiple times. Implies --no-default-groups.
--outdatedShow the latest available version of each package in the tree
--package packageDisplay only the specified packages
--prerelease prereleaseThe 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).
May also be set with the UV_PRERELEASE environment variable.
Possible values:
disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--prune prunePrune the given package from the display of the dependency tree
--python, -p pythonThe Python interpreter to use for locking and filtering.
By default, the tree is filtered to match the platform as reported by the Python interpreter. Use --universal to display the tree for all platforms, or use --python-version or --python-platform to override a subset of markers.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform to use when filtering the tree.
For example, pass --platform windows to display the dependencies that would be included when installing on Windows.
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.
Possible values:
windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--python-version python-versionThe Python version to use when filtering the tree.
For example, pass --python-version 3.10 to display the dependencies that would be included when installing on Python 3.10.
Defaults to the version of the discovered Python interpreter.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--resolution resolutionThe 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).
May also be set with the UV_RESOLUTION environment variable.
Possible values:
highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script scriptShow the dependency tree the specified PEP 723 Python script, rather than the current project.
If provided, uv will resolve the dependencies based on its inline metadata table, in adherence with PEP 723.
--show-sizesShow compressed wheel sizes for packages in the tree
--universalShow a platform-independent dependency tree.
Shows resolved package versions for all Python versions and platforms, rather than filtering to those that are relevant for the current environment.
Multiple versions may be shown for a each package.
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-format","level":2,"title":"uv format","text":"Format Python code in the project.
Formats Python code using the Ruff formatter. By default, all Python files in the project are formatted. This command has the same behavior as running ruff format in the project root.
To check if files are formatted without modifying them, use --check. To see a diff of formatting changes, use --diff.
Additional arguments can be passed to Ruff after --.
Usage uv format [OPTIONS] [-- <EXTRA_ARGS>...]\n
Arguments EXTRA_ARGSAdditional arguments to pass to Ruff.
For example, use uv format -- --line-length 100 to set the line length or uv format -- src/module/foo.py to format a specific file.
Options --allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--checkCheck if files are formatted without applying changes
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--diffShow a diff of formatting changes without applying them.
Implies --check.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-projectAvoid discovering a project or workspace.
Instead of running the formatter in the context of the current project, run it in the context of the current directory. This is useful when the current directory is not a project.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
--version versionThe version of Ruff to use for formatting.
By default, a version of Ruff pinned by uv will be used.
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-tool","level":2,"title":"uv tool","text":"Run and install commands provided by Python packages
Usage uv tool [OPTIONS] <COMMAND>\n
Commands uv tool runRun a command provided by a Python package
uv tool installInstall commands provided by a Python package
uv tool upgradeUpgrade installed tools
uv tool listList installed tools
uv tool uninstallUninstall a tool
uv tool update-shellEnsure that the tool executable directory is on the PATH
uv tool dirShow the path to the uv tools directory
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-tool-run","level":3,"title":"uv tool runUsageOptions","text":"Run a command provided by a Python package.
By default, the package to install is assumed to match the command name.
The name of the command can include an exact version in the format <package>@<version>, e.g., uv tool run ruff@0.3.0. If more complex version specification is desired or if the command is provided by a different package, use --from.
uvx can be used to invoke Python, e.g., with uvx python or uvx python@<version>. A Python interpreter will be started in an isolated virtual environment.
If the tool was previously installed, i.e., via uv tool install, the installed version will be used unless a version is requested or the --isolated flag is used.
uvx is provided as a convenient alias for uv tool run, their behavior is identical.
If no command is provided, the installed tools are displayed.
Packages are installed into an ephemeral virtual environment in the uv cache directory.
uv tool run [OPTIONS] [COMMAND]\n
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--build-constraints, --build-constraint, -b build-constraintsConstrain build dependencies using the given requirements files when building source distributions.
Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
May also be set with the UV_BUILD_CONSTRAINT environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--constraints, --constraint, -c constraintsConstrain versions using the given requirements files.
Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
This is equivalent to pip's --constraint option.
May also be set with the UV_CONSTRAINT environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--env-file env-fileLoad environment variables from a .env file.
Can be provided multiple times, with subsequent files overriding values defined in previous files.
May also be set with the UV_ENV_FILE environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--from fromUse the given package to provide the command.
By default, the package name is assumed to match the command name.
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--isolatedRun the tool in an isolated virtual environment, ignoring any already-installed tools
May also be set with the UV_ISOLATED environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
--no-build-package no-build-packageDon't build source distributions for a specific package
May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-env-fileAvoid reading environment variables from a .env file
May also be set with the UV_NO_ENV_FILE environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--overrides, --override overridesOverride versions using the given requirements files.
Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.
While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.
May also be set with the UV_OVERRIDE environment variable.
--prerelease prereleaseThe 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).
May also be set with the UV_PRERELEASE environment variable.
Possible values:
disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use to build the run environment.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which requirements should be installed.
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.
When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.
Possible values:
windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--refreshRefresh all cached data
--refresh-package refresh-packageRefresh cached data for a specific package
--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
--resolution resolutionThe 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).
May also be set with the UV_RESOLUTION environment variable.
Possible values:
highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
--with, -w withRun with the given packages installed
--with-editable with-editableRun with the given packages installed in editable mode
When used in a project, these dependencies will be layered on top of the uv tool's environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified.
--with-requirements with-requirementsRun with the packages listed in the given files.
The following formats are supported: requirements.txt, .py files with inline metadata, and pylock.toml.
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-tool-install","level":3,"title":"uv tool installUsageArgumentsOptions","text":"Install commands provided by a Python package.
Packages are installed into an isolated virtual environment in the uv tools directory. The executables are linked the tool executable directory, which is determined according to the XDG standard and can be retrieved with uv tool dir --bin.
If the tool was previously installed, the existing tool will generally be replaced.
uv tool install [OPTIONS] <PACKAGE>\n
PACKAGEThe package to install commands from
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--build-constraints, --build-constraint, -b build-constraintsConstrain build dependencies using the given requirements files when building source distributions.
Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
May also be set with the UV_BUILD_CONSTRAINT environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--constraints, --constraint, -c constraintsConstrain versions using the given requirements files.
Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
This is equivalent to pip's --constraint option.
May also be set with the UV_CONSTRAINT environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--editable, -eInstall the target package in editable mode, such that changes in the package's source directory are reflected without reinstallation
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--excludes, --exclude excludesExclude packages from resolution using the given requirements files.
Excludes files are requirements.txt-like files that specify packages to exclude from the resolution. When a package is excluded, it will be omitted from the dependency list entirely and its own dependencies will be ignored during the resolution phase. Excludes are unconditional in that requirement specifiers and markers are ignored; any package listed in the provided file will be omitted from all resolved environments.
May also be set with the UV_EXCLUDE environment variable.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--forceForce installation of the tool.
Will replace any existing entry points with the same name in the executable directory.
--fork-strategy fork-strategyThe 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.
May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
--no-build-package no-build-packageDon't build source distributions for a specific package
May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--overrides, --override overridesOverride versions using the given requirements files.
Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.
While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.
May also be set with the UV_OVERRIDE environment variable.
--prerelease prereleaseThe 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).
May also be set with the UV_PRERELEASE environment variable.
Possible values:
disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use to build the tool environment.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which requirements should be installed.
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.
When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.
Possible values:
windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--refreshRefresh all cached data
--refresh-package refresh-packageRefresh cached data for a specific package
--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
--resolution resolutionThe 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).
May also be set with the UV_RESOLUTION environment variable.
Possible values:
highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
--with, -w withInclude the following additional requirements
--with-editable with-editableInclude the given packages in editable mode
--with-executables-from with-executables-fromInstall executables from the following packages
--with-requirements with-requirementsRun with the packages listed in the given files.
The following formats are supported: requirements.txt, .py files with inline metadata, and pylock.toml.
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-tool-upgrade","level":3,"title":"uv tool upgradeUsageArgumentsOptions","text":"Upgrade installed tools.
If a tool was installed with version constraints, they will be respected on upgrade — to upgrade a tool beyond the originally provided constraints, use uv tool install again.
If a tool was installed with specific settings, they will be respected on upgraded. For example, if --prereleases allow was provided during installation, it will continue to be respected in upgrades.
uv tool upgrade [OPTIONS] <NAME>...\n
NAMEThe name of the tool to upgrade, along with an optional version specifier
--allUpgrade all tools
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-setting-package, --config-settings-package config-setting-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
--no-build-package no-build-packageDon't build source distributions for a specific package
May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--prerelease prereleaseThe 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).
May also be set with the UV_PRERELEASE environment variable.
Possible values:
disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonUpgrade a tool, and specify it to use the given Python interpreter to build its environment. Use with --all to apply to all tools.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which requirements should be installed.
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.
When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.
Possible values:
windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
--resolution resolutionThe 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).
May also be set with the UV_RESOLUTION environment variable.
Possible values:
highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-tool-list","level":3,"title":"uv tool listUsageOptions","text":"List installed tools
uv tool list [OPTIONS]\n
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--show-extrasWhether to display the extra requirements installed with each tool
--show-pathsWhether to display the path to each tool environment and installed executable
--show-pythonWhether to display the Python version associated with each tool
--show-version-specifiersWhether to display the version specifier(s) used to install each tool
--show-withWhether to display the additional requirements installed with each tool
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-tool-uninstall","level":3,"title":"uv tool uninstallUsageArgumentsOptions","text":"Uninstall a tool
uv tool uninstall [OPTIONS] <NAME>...\n
NAMEThe name of the tool to uninstall
--allUninstall all tools
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-tool-update-shell","level":3,"title":"uv tool update-shellUsageOptions","text":"Ensure that the tool executable directory is on the PATH.
If the tool executable directory is not present on the PATH, uv will attempt to add it to the relevant shell configuration files.
If the shell configuration files already include a blurb to add the executable directory to the path, but the directory is not present on the PATH, uv will exit with an error.
The tool executable directory is determined according to the XDG standard and can be retrieved with uv tool dir --bin.
uv tool update-shell [OPTIONS]\n
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-tool-dir","level":3,"title":"uv tool dirUsageOptions","text":"Show the path to the uv tools directory.
The tools directory is used to store environments and metadata for installed tools.
By default, tools are stored in the uv data directory at $XDG_DATA_HOME/uv/tools or $HOME/.local/share/uv/tools on Unix and %APPDATA%\\uv\\data\\tools on Windows.
The tool installation directory may be overridden with $UV_TOOL_DIR.
To instead view the directory uv installs executables into, use the --bin flag.
uv tool dir [OPTIONS]\n
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--binShow the directory into which uv tool will install executables.
By default, uv tool dir shows the directory into which the tool Python environments themselves are installed, rather than the directory containing the linked executables.
The tool executable directory is determined according to the XDG standard and is derived from the following environment variables, in order of preference:
$UV_TOOL_BIN_DIR$XDG_BIN_HOME$XDG_DATA_HOME/../bin$HOME/.local/bin
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-python","level":2,"title":"uv python","text":"Manage Python versions and installations
Generally, uv first searches for Python in a virtual environment, either active or in a .venv directory in the current working directory or any parent directory. If a virtual environment is not required, uv will then search for a Python interpreter. Python interpreters are found by searching for Python executables in the PATH environment variable.
On Windows, the registry is also searched for Python executables.
By default, uv will download Python if a version cannot be found. This behavior can be disabled with the --no-python-downloads flag or the python-downloads setting.
The --python option allows requesting a different interpreter.
The following Python version request formats are supported:
<version> e.g. 3, 3.12, 3.12.3<version-specifier> e.g. >=3.12,<3.13<version><short-variant> (e.g., 3.13t, 3.12.0d)<version>+<variant> (e.g., 3.13+freethreaded, 3.12.0+debug)<implementation> e.g. cpython or cp<implementation>@<version> e.g. cpython@3.12<implementation><version> e.g. cpython3.12 or cp312<implementation><version-specifier> e.g. cpython>=3.12,<3.13<implementation>-<version>-<os>-<arch>-<libc> e.g. cpython-3.12.3-macos-aarch64-none
Additionally, a specific system Python interpreter can often be requested with:
<executable-path> e.g. /opt/homebrew/bin/python3<executable-name> e.g. mypython3<install-dir> e.g. /some/environment/
When the --python option is used, normal discovery rules apply but discovered interpreters are checked for compatibility with the request, e.g., if pypy is requested, uv will first check if the virtual environment contains a PyPy interpreter then check if each executable in the path is a PyPy interpreter.
uv supports discovering CPython, PyPy, and GraalPy interpreters. Unsupported interpreters will be skipped during discovery. If an unsupported interpreter implementation is requested, uv will exit with an error.
Usage uv python [OPTIONS] <COMMAND>\n
Commands uv python listList the available Python installations
uv python installDownload and install Python versions
uv python upgradeUpgrade installed Python versions
uv python findSearch for a Python installation
uv python pinPin to a specific Python version
uv python dirShow the uv Python installation directory
uv python uninstallUninstall Python versions
uv python update-shellEnsure that the Python executable directory is on the PATH
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-python-list","level":3,"title":"uv python listUsageArgumentsOptions","text":"List the available Python installations.
By default, installed Python versions and the downloads for latest available patch version of each supported Python major version are shown.
Use --managed-python to view only managed Python versions.
Use --no-managed-python to omit managed Python versions.
Use --all-versions to view all available patch versions.
Use --only-installed to omit available downloads.
uv python list [OPTIONS] [REQUEST]\n
REQUESTA Python request to filter by.
See uv python to view supported request formats.
--all-arches, --all_architecturesList Python downloads for all architectures.
By default, only downloads for the current architecture are shown.
--all-platformsList Python downloads for all platforms.
By default, only downloads for the current platform are shown.
--all-versionsList all Python versions, including old patch versions.
By default, only the latest patch version is shown for each minor version.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--only-downloadsOnly show available Python downloads.
By default, installed distributions and available downloads for the current platform are shown.
--only-installedOnly show installed Python versions.
By default, installed distributions and available downloads for the current platform are shown.
--output-format output-formatSelect the output format
[default: text]
Possible values:
text: Plain text (for humans)json: JSON (for computers)
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python-downloads-json-url python-downloads-json-urlURL pointing to JSON of custom Python installations.
Note that currently, only local paths are supported.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--show-urlsShow the URLs of available Python downloads.
By default, these display as <download available>.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-python-install","level":3,"title":"uv python installUsageArgumentsOptions","text":"Download and install Python versions.
Supports CPython and PyPy. CPython distributions are downloaded from the Astral python-build-standalone project. PyPy distributions are downloaded from python.org. The available Python versions are bundled with each uv release. To install new Python versions, you may need upgrade uv.
Python versions are installed into the uv Python directory, which can be retrieved with uv python dir.
By default, Python executables are added to a directory on the path with a minor version suffix, e.g., python3.13. To install python3 and python, use the --default flag. Use uv python dir --bin to see the target directory.
Multiple Python versions may be requested.
See uv help python to view supported request formats.
uv python install [OPTIONS] [TARGETS]...\n
TARGETSThe Python version(s) to install.
If not provided, the requested Python version(s) will be read from the UV_PYTHON environment variable then .python-versions or .python-version files. If none of the above are present, uv will check if it has installed any Python versions. If not, it will install the latest stable version of Python.
See uv python to view supported request formats.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--defaultUse as the default Python version.
By default, only a python{major}.{minor} executable is installed, e.g., python3.10. When the --default flag is used, python{major}, e.g., python3, and python executables are also installed.
Alternative Python variants will still include their tag. For example, installing 3.13+freethreaded with --default will include in python3t and pythont, not python3 and python.
If multiple Python versions are requested, uv will exit with an error.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--force, -fReplace existing Python executables during installation.
By default, uv will refuse to replace executables that it does not manage.
Implies --reinstall.
--help, -hDisplay the concise help for this command
--install-dir, -i install-dirThe directory to store the Python installation in.
If provided, UV_PYTHON_INSTALL_DIR will need to be set for subsequent operations for uv to discover the Python installation.
See uv python dir to view the current Python installation directory. Defaults to ~/.local/share/uv/python.
May also be set with the UV_PYTHON_INSTALL_DIR environment variable.
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--mirror mirrorSet the URL to use as the source for downloading Python installations.
The provided URL will replace https://github.com/astral-sh/python-build-standalone/releases/download in, e.g., https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz.
Distributions can be read from a local directory by using the file:// URL scheme.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-binDo not install a Python executable into the bin directory.
This can also be set with UV_PYTHON_INSTALL_BIN=0.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-registryDo not register the Python installation in the Windows registry.
This can also be set with UV_PYTHON_INSTALL_REGISTRY=0.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--pypy-mirror pypy-mirrorSet the URL to use as the source for downloading PyPy installations.
The provided URL will replace https://downloads.python.org/pypy in, e.g., https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2.
Distributions can be read from a local directory by using the file:// URL scheme.
--python-downloads-json-url python-downloads-json-urlURL pointing to JSON of custom Python installations.
Note that currently, only local paths are supported.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--reinstall, -rReinstall the requested Python version, if it's already installed.
By default, uv will exit successfully if the version is already installed.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-python-upgrade","level":3,"title":"uv python upgradeUsageArgumentsOptions","text":"Upgrade installed Python versions.
Upgrades versions to the latest supported patch release. Requires the python-upgrade preview feature.
A target Python minor version to upgrade may be provided, e.g., 3.13. Multiple versions may be provided to perform more than one upgrade.
If no target version is provided, then uv will upgrade all managed CPython versions.
During an upgrade, uv will not uninstall outdated patch versions.
When an upgrade is performed, virtual environments created by uv will automatically use the new version. However, if the virtual environment was created before the upgrade functionality was added, it will continue to use the old Python version; to enable upgrades, the environment must be recreated.
Upgrades are not yet supported for alternative implementations, like PyPy.
uv python upgrade [OPTIONS] [TARGETS]...\n
TARGETSThe Python minor version(s) to upgrade.
If no target version is provided, then uv will upgrade all managed CPython versions.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--install-dir, -i install-dirThe directory Python installations are stored in.
If provided, UV_PYTHON_INSTALL_DIR will need to be set for subsequent operations for uv to discover the Python installation.
See uv python dir to view the current Python installation directory. Defaults to ~/.local/share/uv/python.
May also be set with the UV_PYTHON_INSTALL_DIR environment variable.
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--mirror mirrorSet the URL to use as the source for downloading Python installations.
The provided URL will replace https://github.com/astral-sh/python-build-standalone/releases/download in, e.g., https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz.
Distributions can be read from a local directory by using the file:// URL scheme.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--pypy-mirror pypy-mirrorSet the URL to use as the source for downloading PyPy installations.
The provided URL will replace https://downloads.python.org/pypy in, e.g., https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2.
Distributions can be read from a local directory by using the file:// URL scheme.
--python-downloads-json-url python-downloads-json-urlURL pointing to JSON of custom Python installations.
Note that currently, only local paths are supported.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--reinstall, -rReinstall the latest Python patch, if it's already installed.
By default, uv will exit successfully if the latest patch is already installed.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-python-find","level":3,"title":"uv python findUsageArgumentsOptions","text":"Search for a Python installation.
Displays the path to the Python executable.
See uv help python to view supported request formats and details on discovery behavior.
uv python find [OPTIONS] [REQUEST]\n
REQUESTThe Python request.
See uv python to view supported request formats.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-project, --no_workspaceAvoid discovering a project or workspace.
Otherwise, when no request is provided, the Python requirement of a project in the current directory or parent directories will be used.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--script scriptFind the environment for a Python script, rather than the current project
--show-versionShow the Python version that would be used instead of the path to the interpreter
--systemOnly find system Python interpreters.
By default, uv will report the first Python interpreter it would use, including those in an active virtual environment or a virtual environment in the current working directory or any parent directory.
The --system option instructs uv to skip virtual environment Python interpreters and restrict its search to the system path.
May also be set with the UV_SYSTEM_PYTHON environment variable.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-python-pin","level":3,"title":"uv python pinUsageArgumentsOptions","text":"Pin to a specific Python version.
Writes the pinned Python version to a .python-version file, which is used by other uv commands to determine the required Python version.
If no version is provided, uv will look for an existing .python-version file and display the currently pinned version. If no .python-version file is found, uv will exit with an error.
See uv help python to view supported request formats.
uv python pin [OPTIONS] [REQUEST]\n
REQUESTThe Python version request.
uv supports more formats than other tools that read .python-version files, i.e., pyenv. If compatibility with those tools is needed, only use version numbers instead of complex requests such as cpython@3.10.
If no request is provided, the currently pinned version will be shown.
See uv python to view supported request formats.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--globalUpdate the global Python version pin.
Writes the pinned Python version to a .python-version file in the uv user configuration directory: XDG_CONFIG_HOME/uv on Linux/macOS and %APPDATA%/uv on Windows.
When a local Python version pin is not found in the working directory or an ancestor directory, this version will be used instead.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-project, --no-workspaceAvoid validating the Python pin is compatible with the project or workspace.
By default, a project or workspace is discovered in the current directory or any parent directory. If a workspace is found, the Python pin is validated against the workspace's requires-python constraint.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--resolvedWrite the resolved Python interpreter path instead of the request.
Ensures that the exact same interpreter is used.
This option is usually not safe to use when committing the .python-version file to version control.
--rmRemove the Python version pin
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-python-dir","level":3,"title":"uv python dirUsageOptions","text":"Show the uv Python installation directory.
By default, Python installations are stored in the uv data directory at $XDG_DATA_HOME/uv/python or $HOME/.local/share/uv/python on Unix and %APPDATA%\\uv\\data\\python on Windows.
The Python installation directory may be overridden with $UV_PYTHON_INSTALL_DIR.
To view the directory where uv installs Python executables instead, use the --bin flag. The Python executable directory may be overridden with $UV_PYTHON_BIN_DIR. Note that Python executables are only installed when preview mode is enabled.
uv python dir [OPTIONS]\n
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--binShow the directory into which uv python will install Python executables.
Note that this directory is only used when installing Python with preview mode enabled.
The Python executable directory is determined according to the XDG standard and is derived from the following environment variables, in order of preference:
$UV_PYTHON_BIN_DIR$XDG_BIN_HOME$XDG_DATA_HOME/../bin$HOME/.local/bin
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-python-uninstall","level":3,"title":"uv python uninstallUsageArgumentsOptions","text":"Uninstall Python versions
uv python uninstall [OPTIONS] <TARGETS>...\n
TARGETSThe Python version(s) to uninstall.
See uv python to view supported request formats.
--allUninstall all managed Python versions
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--install-dir, -i install-dirThe directory where the Python was installed
May also be set with the UV_PYTHON_INSTALL_DIR environment variable.
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-python-update-shell","level":3,"title":"uv python update-shellUsageOptions","text":"Ensure that the Python executable directory is on the PATH.
If the Python executable directory is not present on the PATH, uv will attempt to add it to the relevant shell configuration files.
If the shell configuration files already include a blurb to add the executable directory to the path, but the directory is not present on the PATH, uv will exit with an error.
The Python executable directory is determined according to the XDG standard and can be retrieved with uv python dir --bin.
uv python update-shell [OPTIONS]\n
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-pip","level":2,"title":"uv pip","text":"Manage Python packages with a pip-compatible interface
Usage uv pip [OPTIONS] <COMMAND>\n
Commands uv pip compileCompile a requirements.in file to a requirements.txt or pylock.toml file
uv pip syncSync an environment with a requirements.txt or pylock.toml file
uv pip installInstall packages into an environment
uv pip uninstallUninstall packages from an environment
uv pip freezeList, in requirements format, packages installed in an environment
uv pip listList, in tabular format, packages installed in an environment
uv pip showShow information about one or more installed packages
uv pip treeDisplay the dependency tree for an environment
uv pip checkVerify installed packages have compatible dependencies
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-pip-compile","level":3,"title":"uv pip compileUsageArgumentsOptions","text":"Compile a requirements.in file to a requirements.txt or pylock.toml file
uv pip compile [OPTIONS] <SRC_FILE|--group <GROUP>>\n
SRC_FILEInclude the packages listed in the given files.
The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.
If a pyproject.toml, setup.py, or setup.cfg file is provided, uv will extract the requirements for the relevant project.
If - is provided, then requirements will be read from stdin.
The order of the requirements files and the requirements in them is used to determine priority during resolution.
--all-extrasInclude all optional dependencies.
Only applies to pyproject.toml, setup.py, and setup.cfg sources.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--annotation-style annotation-styleThe style of the annotation comments included in the output file, used to indicate the source of each package.
Defaults to split.
Possible values:
line: Render the annotations on a single, comma-separated linesplit: Render each annotation on its own line
--build-constraints, --build-constraint, -b build-constraintsConstrain build dependencies using the given requirements files when building source distributions.
Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
May also be set with the UV_BUILD_CONSTRAINT environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--constraints, --constraint, -c constraintsConstrain versions using the given requirements files.
Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
This is equivalent to pip's --constraint option.
May also be set with the UV_CONSTRAINT environment variable.
--custom-compile-command custom-compile-commandThe 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.
May also be set with the UV_CUSTOM_COMPILE_COMMAND environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--emit-build-optionsInclude --no-binary and --only-binary entries in the generated output file
--emit-find-linksInclude --find-links entries in the generated output file
--emit-index-annotationInclude comment annotations indicating the index used to resolve each package (e.g., # from https://pypi.org/simple)
--emit-index-urlInclude --index-url and --extra-index-url entries in the generated output file
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for a specific package to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--excludes, --exclude excludesExclude packages from resolution using the given requirements files.
Excludes files are requirements.txt-like files that specify packages to exclude from the resolution. When a package is excluded, it will be omitted from the dependency list entirely and its own dependencies will be ignored during the resolution phase. Excludes are unconditional in that requirement specifiers and markers are ignored; any package listed in the provided file will be omitted from all resolved environments.
May also be set with the UV_EXCLUDE environment variable.
--extra extraInclude optional dependencies from the specified extra name; may be provided more than once.
Only applies to pyproject.toml, setup.py, and setup.cfg sources.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--format formatThe format in which the resolution should be output.
Supports both requirements.txt and pylock.toml (PEP 751) output formats.
uv will infer the output format from the file extension of the output file, if provided. Otherwise, defaults to requirements.txt.
Possible values:
requirements.txt: Export in requirements.txt formatpylock.toml: Export in pylock.toml format
--generate-hashesInclude distribution hashes in the output file
--group groupInstall the specified dependency group from a pyproject.toml.
If no path is provided, the pyproject.toml in the working directory is used.
May be provided multiple times.
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
This option is only used when building source distributions.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-annotateExclude comment annotations indicating the source of each package
--no-binary no-binaryDon'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:.
--no-buildDon'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:.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-depsIgnore package dependencies, instead only add those packages explicitly listed on the command line to the resulting requirements file
--no-emit-package, --unsafe-package no-emit-packageSpecify 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
--no-headerExclude the comment header at the top of the generated output file
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--no-strip-extrasInclude 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.
--no-strip-markersInclude environment markers in the output file.
By default, uv strips environment markers, as the resolution generated by compile is only guaranteed to be correct for the target environment.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--only-binary only-binaryOnly 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:.
--output-file, -o output-fileWrite the compiled requirements to the given requirements.txt or pylock.toml file.
If the file already exists, the existing versions will be preferred when resolving dependencies, unless --upgrade is also specified.
--overrides, --override overridesOverride versions using the given requirements files.
Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.
While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.
May also be set with the UV_OVERRIDE environment variable.
--prerelease prereleaseThe 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).
May also be set with the UV_PRERELEASE environment variable.
Possible values:
disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use during resolution.
A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.
The interpreter is also used to determine the default minimum Python version, unless --python-version is provided.
This option respects UV_PYTHON, but when set via environment variable, it is overridden by --python-version.
See uv python for details on Python discovery and supported request formats.
--python-platform python-platformThe 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.
When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
Possible values:
windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--python-version python-versionThe Python version to use for resolution.
For example, 3.8 or 3.8.17.
Defaults to the version of the Python interpreter used for resolution.
Defines the minimum Python version that must be supported by the resolved requirements.
If a patch version is omitted, the minimum patch version is assumed. For example, 3.8 is mapped to 3.8.0.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--refreshRefresh all cached data
--refresh-package refresh-packageRefresh cached data for a specific package
--resolution resolutionThe 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).
May also be set with the UV_RESOLUTION environment variable.
Possible values:
highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--systemInstall packages into the system Python environment.
By default, uv uses the virtual environment in the current working directory or any parent directory, falling back to searching for a Python executable in PATH. The --system option instructs uv to avoid using a virtual environment Python and restrict its search to the system path.
May also be set with the UV_SYSTEM_PYTHON environment variable.
--torch-backend torch-backendThe backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto).
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 option is in preview and may change in any future release.
May also be set with the UV_TORCH_BACKEND environment variable.
Possible values:
auto: Select the appropriate PyTorch index based on the operating system and CUDA driver versioncpu: Use the CPU-only PyTorch indexcu130: Use the PyTorch index for CUDA 13.0cu129: Use the PyTorch index for CUDA 12.9cu128: Use the PyTorch index for CUDA 12.8cu126: Use the PyTorch index for CUDA 12.6cu125: Use the PyTorch index for CUDA 12.5cu124: Use the PyTorch index for CUDA 12.4cu123: Use the PyTorch index for CUDA 12.3cu122: Use the PyTorch index for CUDA 12.2cu121: Use the PyTorch index for CUDA 12.1cu120: Use the PyTorch index for CUDA 12.0cu118: Use the PyTorch index for CUDA 11.8cu117: Use the PyTorch index for CUDA 11.7cu116: Use the PyTorch index for CUDA 11.6cu115: Use the PyTorch index for CUDA 11.5cu114: Use the PyTorch index for CUDA 11.4cu113: Use the PyTorch index for CUDA 11.3cu112: Use the PyTorch index for CUDA 11.2cu111: Use the PyTorch index for CUDA 11.1cu110: Use the PyTorch index for CUDA 11.0cu102: Use the PyTorch index for CUDA 10.2cu101: Use the PyTorch index for CUDA 10.1cu100: Use the PyTorch index for CUDA 10.0cu92: Use the PyTorch index for CUDA 9.2cu91: Use the PyTorch index for CUDA 9.1cu90: Use the PyTorch index for CUDA 9.0cu80: Use the PyTorch index for CUDA 8.0rocm6.3: Use the PyTorch index for ROCm 6.3rocm6.2.4: Use the PyTorch index for ROCm 6.2.4rocm6.2: Use the PyTorch index for ROCm 6.2rocm6.1: Use the PyTorch index for ROCm 6.1rocm6.0: Use the PyTorch index for ROCm 6.0rocm5.7: Use the PyTorch index for ROCm 5.7rocm5.6: Use the PyTorch index for ROCm 5.6rocm5.5: Use the PyTorch index for ROCm 5.5rocm5.4.2: Use the PyTorch index for ROCm 5.4.2rocm5.4: Use the PyTorch index for ROCm 5.4rocm5.3: Use the PyTorch index for ROCm 5.3rocm5.2: Use the PyTorch index for ROCm 5.2rocm5.1.1: Use the PyTorch index for ROCm 5.1.1rocm4.2: Use the PyTorch index for ROCm 4.2rocm4.1: Use the PyTorch index for ROCm 4.1rocm4.0.1: Use the PyTorch index for ROCm 4.0.1xpu: Use the PyTorch index for Intel XPU
--universalPerform 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.
Implies --no-strip-markers.
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-pip-sync","level":3,"title":"uv pip syncUsageArgumentsOptions","text":"Sync an environment with a requirements.txt or pylock.toml file.
When syncing an environment, any packages not listed in the requirements.txt or pylock.toml file will be removed. To retain extraneous packages, use uv pip install instead.
The input file is presumed to be the output of a pip compile or uv export operation, in which it will include all transitive dependencies. If transitive dependencies are not present in the file, they will not be installed. Use --strict to warn if any transitive dependencies are missing.
uv pip sync [OPTIONS] <SRC_FILE>...\n
SRC_FILEInclude the packages listed in the given files.
The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.
If a pyproject.toml, setup.py, or setup.cfg file is provided, uv will extract the requirements for the relevant project.
If - is provided, then requirements will be read from stdin.
--all-extrasInclude all optional dependencies.
Only applies to pylock.toml, pyproject.toml, setup.py, and setup.cfg sources.
--allow-empty-requirementsAllow sync of empty requirements, which will clear the environment of all packages
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--break-system-packagesAllow 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).
May also be set with the UV_BREAK_SYSTEM_PACKAGES environment variable.
--build-constraints, --build-constraint, -b build-constraintsConstrain build dependencies using the given requirements files when building source distributions.
Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
May also be set with the UV_BUILD_CONSTRAINT environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--constraints, --constraint, -c constraintsConstrain versions using the given requirements files.
Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
This is equivalent to pip's --constraint option.
May also be set with the UV_CONSTRAINT environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runPerform a dry run, i.e., don't actually install anything but resolve the dependencies and print the resulting plan
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--extra extraInclude optional dependencies from the specified extra name; may be provided more than once.
Only applies to pylock.toml, pyproject.toml, setup.py, and setup.cfg sources.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--group groupInstall the specified dependency group from a pylock.toml or pyproject.toml.
If no path is provided, the pylock.toml or pyproject.toml in the working directory is used.
May be provided multiple times.
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-allow-empty-requirements--no-binary no-binaryDon'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:.
--no-break-system-packages--no-buildDon'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:.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--no-verify-hashesDisable validation of hashes in the requirements file.
By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash. To enforce hash validation, use --require-hashes.
May also be set with the UV_NO_VERIFY_HASHES environment variable.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--only-binary only-binaryOnly 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:.
--prefix prefixInstall 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.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter into which packages should be installed.
By default, syncing requires a virtual environment. A path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which requirements should be installed.
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.
When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.
Possible values:
windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--python-version python-versionThe minimum Python version that should be supported by the requirements (e.g., 3.7 or 3.7.9).
If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--refreshRefresh all cached data
--refresh-package refresh-packageRefresh cached data for a specific package
--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
--require-hashesRequire a matching hash for each requirement.
By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash.
When --require-hashes is enabled, all requirements must include a hash or set of hashes, and 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.
May also be set with the UV_REQUIRE_HASHES environment variable.
--strictValidate the Python environment after completing the installation, to detect packages with missing dependencies or other issues
--systemInstall 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.
May also be set with the UV_SYSTEM_PYTHON environment variable.
--target targetInstall 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
--torch-backend torch-backendThe backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto).
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 option is in preview and may change in any future release.
May also be set with the UV_TORCH_BACKEND environment variable.
Possible values:
auto: Select the appropriate PyTorch index based on the operating system and CUDA driver versioncpu: Use the CPU-only PyTorch indexcu130: Use the PyTorch index for CUDA 13.0cu129: Use the PyTorch index for CUDA 12.9cu128: Use the PyTorch index for CUDA 12.8cu126: Use the PyTorch index for CUDA 12.6cu125: Use the PyTorch index for CUDA 12.5cu124: Use the PyTorch index for CUDA 12.4cu123: Use the PyTorch index for CUDA 12.3cu122: Use the PyTorch index for CUDA 12.2cu121: Use the PyTorch index for CUDA 12.1cu120: Use the PyTorch index for CUDA 12.0cu118: Use the PyTorch index for CUDA 11.8cu117: Use the PyTorch index for CUDA 11.7cu116: Use the PyTorch index for CUDA 11.6cu115: Use the PyTorch index for CUDA 11.5cu114: Use the PyTorch index for CUDA 11.4cu113: Use the PyTorch index for CUDA 11.3cu112: Use the PyTorch index for CUDA 11.2cu111: Use the PyTorch index for CUDA 11.1cu110: Use the PyTorch index for CUDA 11.0cu102: Use the PyTorch index for CUDA 10.2cu101: Use the PyTorch index for CUDA 10.1cu100: Use the PyTorch index for CUDA 10.0cu92: Use the PyTorch index for CUDA 9.2cu91: Use the PyTorch index for CUDA 9.1cu90: Use the PyTorch index for CUDA 9.0cu80: Use the PyTorch index for CUDA 8.0rocm6.3: Use the PyTorch index for ROCm 6.3rocm6.2.4: Use the PyTorch index for ROCm 6.2.4rocm6.2: Use the PyTorch index for ROCm 6.2rocm6.1: Use the PyTorch index for ROCm 6.1rocm6.0: Use the PyTorch index for ROCm 6.0rocm5.7: Use the PyTorch index for ROCm 5.7rocm5.6: Use the PyTorch index for ROCm 5.6rocm5.5: Use the PyTorch index for ROCm 5.5rocm5.4.2: Use the PyTorch index for ROCm 5.4.2rocm5.4: Use the PyTorch index for ROCm 5.4rocm5.3: Use the PyTorch index for ROCm 5.3rocm5.2: Use the PyTorch index for ROCm 5.2rocm5.1.1: Use the PyTorch index for ROCm 5.1.1rocm4.2: Use the PyTorch index for ROCm 4.2rocm4.1: Use the PyTorch index for ROCm 4.1rocm4.0.1: Use the PyTorch index for ROCm 4.0.1xpu: Use the PyTorch index for Intel XPU
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-pip-install","level":3,"title":"uv pip installUsageArgumentsOptions","text":"Install packages into an environment
uv pip install [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>|--editable <EDITABLE>|--group <GROUP>>\n
PACKAGEInstall all listed packages.
The order of the packages is used to determine priority during resolution.
--all-extrasInclude all optional dependencies.
Only applies to pylock.toml, pyproject.toml, setup.py, and setup.cfg sources.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--break-system-packagesAllow 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).
May also be set with the UV_BREAK_SYSTEM_PACKAGES environment variable.
--build-constraints, --build-constraint, -b build-constraintsConstrain build dependencies using the given requirements files when building source distributions.
Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
May also be set with the UV_BUILD_CONSTRAINT environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--compile-bytecode, --compileCompile 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.
May also be set with the UV_COMPILE_BYTECODE environment variable.
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--constraints, --constraint, -c constraintsConstrain versions using the given requirements files.
Constraints files are requirements.txt-like files that only control the version of a requirement that's installed. However, including a package in a constraints file will not trigger the installation of that package.
This is equivalent to pip's --constraint option.
May also be set with the UV_CONSTRAINT environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runPerform a dry run, i.e., don't actually install anything but resolve the dependencies and print the resulting plan
--editable, -e editableInstall the editable package based on the provided local file path
--exactPerform an exact sync, removing extraneous packages.
By default, installing will make the minimum necessary changes to satisfy the requirements. When enabled, uv will update the environment to exactly match the requirements, removing packages that are not included in the requirements.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for specific packages to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--excludes, --exclude excludesExclude packages from resolution using the given requirements files.
Excludes files are requirements.txt-like files that specify packages to exclude from the resolution. When a package is excluded, it will be omitted from the dependency list entirely and its own dependencies will be ignored during the resolution phase. Excludes are unconditional in that requirement specifiers and markers are ignored; any package listed in the provided file will be omitted from all resolved environments.
May also be set with the UV_EXCLUDE environment variable.
--extra extraInclude optional dependencies from the specified extra name; may be provided more than once.
Only applies to pylock.toml, pyproject.toml, setup.py, and setup.cfg sources.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--fork-strategy fork-strategyThe 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.
May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--group groupInstall the specified dependency group from a pylock.toml or pyproject.toml.
If no path is provided, the pylock.toml or pyproject.toml in the working directory is used.
May be provided multiple times.
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-binary no-binaryDon'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:.
--no-break-system-packages--no-buildDon'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:.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-depsIgnore package dependencies, instead only installing those packages explicitly listed on the command line or in the requirements files
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--no-verify-hashesDisable validation of hashes in the requirements file.
By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash. To enforce hash validation, use --require-hashes.
May also be set with the UV_NO_VERIFY_HASHES environment variable.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--only-binary only-binaryOnly 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:.
--overrides, --override overridesOverride versions using the given requirements files.
Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.
While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.
May also be set with the UV_OVERRIDE environment variable.
--prefix prefixInstall 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.
--prerelease prereleaseThe 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).
May also be set with the UV_PRERELEASE environment variable.
Possible values:
disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter into which packages should be installed.
By default, installation requires a virtual environment. A path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which requirements should be installed.
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.
When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.
Possible values:
windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--python-version python-versionThe minimum Python version that should be supported by the requirements (e.g., 3.7 or 3.7.9).
If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--refreshRefresh all cached data
--refresh-package refresh-packageRefresh cached data for a specific package
--reinstall, --force-reinstallReinstall all packages, regardless of whether they're already installed. Implies --refresh
--reinstall-package reinstall-packageReinstall a specific package, regardless of whether it's already installed. Implies --refresh-package
--require-hashesRequire a matching hash for each requirement.
By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash.
When --require-hashes is enabled, all requirements must include a hash or set of hashes, and 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.
May also be set with the UV_REQUIRE_HASHES environment variable.
--requirements, --requirement, -r requirementsInstall the packages listed in the given files.
The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.
If a pyproject.toml, setup.py, or setup.cfg file is provided, uv will extract the requirements for the relevant project.
If - is provided, then requirements will be read from stdin.
--resolution resolutionThe 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).
May also be set with the UV_RESOLUTION environment variable.
Possible values:
highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--strictValidate the Python environment after completing the installation, to detect packages with missing dependencies or other issues
--systemInstall 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.
May also be set with the UV_SYSTEM_PYTHON environment variable.
--target targetInstall 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
--torch-backend torch-backendThe backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto)
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 option is in preview and may change in any future release.
May also be set with the UV_TORCH_BACKEND environment variable.
Possible values:
auto: Select the appropriate PyTorch index based on the operating system and CUDA driver versioncpu: Use the CPU-only PyTorch indexcu130: Use the PyTorch index for CUDA 13.0cu129: Use the PyTorch index for CUDA 12.9cu128: Use the PyTorch index for CUDA 12.8cu126: Use the PyTorch index for CUDA 12.6cu125: Use the PyTorch index for CUDA 12.5cu124: Use the PyTorch index for CUDA 12.4cu123: Use the PyTorch index for CUDA 12.3cu122: Use the PyTorch index for CUDA 12.2cu121: Use the PyTorch index for CUDA 12.1cu120: Use the PyTorch index for CUDA 12.0cu118: Use the PyTorch index for CUDA 11.8cu117: Use the PyTorch index for CUDA 11.7cu116: Use the PyTorch index for CUDA 11.6cu115: Use the PyTorch index for CUDA 11.5cu114: Use the PyTorch index for CUDA 11.4cu113: Use the PyTorch index for CUDA 11.3cu112: Use the PyTorch index for CUDA 11.2cu111: Use the PyTorch index for CUDA 11.1cu110: Use the PyTorch index for CUDA 11.0cu102: Use the PyTorch index for CUDA 10.2cu101: Use the PyTorch index for CUDA 10.1cu100: Use the PyTorch index for CUDA 10.0cu92: Use the PyTorch index for CUDA 9.2cu91: Use the PyTorch index for CUDA 9.1cu90: Use the PyTorch index for CUDA 9.0cu80: Use the PyTorch index for CUDA 8.0rocm6.3: Use the PyTorch index for ROCm 6.3rocm6.2.4: Use the PyTorch index for ROCm 6.2.4rocm6.2: Use the PyTorch index for ROCm 6.2rocm6.1: Use the PyTorch index for ROCm 6.1rocm6.0: Use the PyTorch index for ROCm 6.0rocm5.7: Use the PyTorch index for ROCm 5.7rocm5.6: Use the PyTorch index for ROCm 5.6rocm5.5: Use the PyTorch index for ROCm 5.5rocm5.4.2: Use the PyTorch index for ROCm 5.4.2rocm5.4: Use the PyTorch index for ROCm 5.4rocm5.3: Use the PyTorch index for ROCm 5.3rocm5.2: Use the PyTorch index for ROCm 5.2rocm5.1.1: Use the PyTorch index for ROCm 5.1.1rocm4.2: Use the PyTorch index for ROCm 4.2rocm4.1: Use the PyTorch index for ROCm 4.1rocm4.0.1: Use the PyTorch index for ROCm 4.0.1xpu: Use the PyTorch index for Intel XPU
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
--user--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-pip-uninstall","level":3,"title":"uv pip uninstallUsageArgumentsOptions","text":"Uninstall packages from an environment
uv pip uninstall [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>>\n
PACKAGEUninstall all listed packages
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--break-system-packagesAllow 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).
May also be set with the UV_BREAK_SYSTEM_PACKAGES environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runPerform a dry run, i.e., don't actually uninstall anything but print the resulting plan
--help, -hDisplay the concise help for this command
--keyring-provider keyring-providerAttempt to use keyring for authentication for remote requirements files.
At present, only --keyring-provider subprocess is supported, which configures uv to use the keyring CLI to handle authentication.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-break-system-packages--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--prefix prefixUninstall packages from the specified --prefix directory
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter from which packages should be uninstalled.
By default, uninstallation requires a virtual environment. A path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--requirements, --requirement, -r requirementsUninstall the packages listed in the given files.
The following formats are supported: requirements.txt, .py files with inline metadata, pylock.toml, pyproject.toml, setup.py, and setup.cfg.
--systemUse the system Python to uninstall packages.
By default, uv uninstalls from 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.
May also be set with the UV_SYSTEM_PYTHON environment variable.
--target targetUninstall packages from the specified --target directory
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-pip-freeze","level":3,"title":"uv pip freezeUsageOptions","text":"List, in requirements format, packages installed in an environment
uv pip freeze [OPTIONS]\n
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-editableExclude any editable packages from output
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--path pathsRestrict to the specified installation path for listing packages (can be used multiple times)
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter for which packages should be listed.
By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--strictValidate the Python environment, to detect packages with missing dependencies and other issues
--systemList packages in the system Python environment.
Disables discovery of virtual environments.
See uv python for details on Python discovery.
May also be set with the UV_SYSTEM_PYTHON environment variable.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-pip-list","level":3,"title":"uv pip listUsageOptions","text":"List, in tabular format, packages installed in an environment
uv pip list [OPTIONS]\n
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--editable, -eOnly include editable projects
--exclude excludeExclude the specified package(s) from the output
--exclude-editableExclude any editable packages from output
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--format formatSelect the output format
[default: columns]
Possible values:
columns: Display the list of packages in a human-readable tablefreeze: Display the list of packages in a pip freeze-like format, with one package per line alongside its versionjson: Display the list of packages in a machine-readable JSON format
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--outdatedList outdated packages.
The latest version of each package will be shown alongside the installed version. Up-to-date packages will be omitted from the output.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter for which packages should be listed.
By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--strictValidate the Python environment, to detect packages with missing dependencies and other issues
--systemList packages in the system Python environment.
Disables discovery of virtual environments.
See uv python for details on Python discovery.
May also be set with the UV_SYSTEM_PYTHON environment variable.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-pip-show","level":3,"title":"uv pip showUsageArgumentsOptions","text":"Show information about one or more installed packages
uv pip show [OPTIONS] [PACKAGE]...\n
PACKAGEThe package(s) to display
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--files, -fShow the full list of installed files for each package
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to find the package in.
By default, uv looks for packages in a virtual environment but will look for packages in a system Python environment if no virtual environment is found.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--strictValidate the Python environment, to detect packages with missing dependencies and other issues
--systemShow a package in the system Python environment.
Disables discovery of virtual environments.
See uv python for details on Python discovery.
May also be set with the UV_SYSTEM_PYTHON environment variable.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-pip-tree","level":3,"title":"uv pip treeUsageOptions","text":"Display the dependency tree for an environment
uv pip tree [OPTIONS]\n
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--depth, -d depthMaximum display depth of the dependency tree
[default: 255]
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--invert, --reverseShow the reverse dependencies for the given package. This flag will invert the tree and display the packages that depend on the given package
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-dedupeDo not de-duplicate repeated dependencies. Usually, when a package has already displayed its dependencies, further occurrences will not re-display its dependencies, and will include a (*) to indicate it has already been shown. This flag will cause those duplicates to be repeated
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--outdatedShow the latest available version of each package in the tree
--package packageDisplay only the specified packages
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--prune prunePrune the given package from the display of the dependency tree
--python, -p pythonThe Python interpreter for which packages should be listed.
By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--show-sizesShow compressed wheel sizes for packages in the tree
--show-version-specifiersShow the version constraint(s) imposed on each package
--strictValidate the Python environment, to detect packages with missing dependencies and other issues
--systemList packages in the system Python environment.
Disables discovery of virtual environments.
See uv python for details on Python discovery.
May also be set with the UV_SYSTEM_PYTHON environment variable.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-pip-check","level":3,"title":"uv pip checkUsageOptions","text":"Verify installed packages have compatible dependencies
uv pip check [OPTIONS]\n
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter for which packages should be checked.
By default, uv checks packages in a virtual environment but will check packages in a system Python environment if no virtual environment is found.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--python-platform python-platformThe platform for which packages should be checked.
By default, the installed packages are checked against the platform of the current interpreter.
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.
When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.
When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.
Possible values:
windows: An alias for x86_64-pc-windows-msvc, the default target for Windowslinux: An alias for x86_64-unknown-linux-gnu, the default target for Linuxmacos: An alias for aarch64-apple-darwin, the default target for macOSx86_64-pc-windows-msvc: A 64-bit x86 Windows targetaarch64-pc-windows-msvc: An ARM64 Windows targeti686-pc-windows-msvc: A 32-bit x86 Windows targetx86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devicesx86_64-apple-darwin: An x86 macOS targetaarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28aarch64-unknown-linux-musl: An ARM64 Linux targetx86_64-unknown-linux-musl: An x86_64 Linux targetriscv64-unknown-linux: A RISCV64 Linux targetx86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platformx86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platformx86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platformx86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platformx86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platformx86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platformx86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platformx86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platformx86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platformx86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platformx86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platformx86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platformaarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platformaarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platformaarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platformaarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platformaarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platformaarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platformaarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platformaarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platformaarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platformaarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platformaarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platformaarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platformaarch64-linux-android: An ARM64 Android targetx86_64-linux-android: An x86_64 Android targetwasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12arm64-apple-ios: An ARM64 target for iOS devicearm64-apple-ios-simulator: An ARM64 target for iOS simulatorx86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--python-version python-versionThe Python version against which packages should be checked.
By default, the installed packages are checked against the version of the current interpreter.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--systemCheck packages in the system Python environment.
Disables discovery of virtual environments.
See uv python for details on Python discovery.
May also be set with the UV_SYSTEM_PYTHON environment variable.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-venv","level":2,"title":"uv venv","text":"Create a virtual environment.
By default, creates a virtual environment named .venv in the working directory. An alternative path may be provided positionally.
If in a project, the default environment name can be changed with the UV_PROJECT_ENVIRONMENT environment variable; this only applies when run from the project root directory.
If a virtual environment exists at the target path, it will be removed and a new, empty virtual environment will be created.
When using uv, the virtual environment does not need to be activated. uv will find a virtual environment (named .venv) in the working directory or any parent directories.
Usage uv venv [OPTIONS] [PATH]\n
Arguments PATHThe path to the virtual environment to create.
Default to .venv in the working directory.
Relative paths are resolved relative to the working directory.
Options --allow-existingPreserve any existing files or directories at the target path.
By default, uv venv will exit with an error if the given path is non-empty. The --allow-existing option will instead write to the given path, regardless of its contents, and without clearing it beforehand.
WARNING: This option can lead to unexpected behavior if the existing virtual environment and the newly-created virtual environment are linked to different Python interpreters.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--clear, -cRemove any existing files or directories at the target path.
By default, uv venv will exit with an error if the given path is non-empty. The --clear option will instead clear a non-empty path before creating a new virtual environment.
May also be set with the UV_VENV_CLEAR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for a specific package to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
This option is only used for installing seed packages.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-project, --no-workspaceAvoid discovering a project or workspace.
By default, uv searches for projects in the current directory or any parent directory to determine the default path of the virtual environment and check for Python version constraints, if any.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--prompt promptProvide an alternative prompt prefix for the virtual environment.
By default, the prompt is dependent on whether a path was provided to uv venv. If provided (e.g, uv venv project), the prompt is set to the directory name. If not provided (uv venv), the prompt is set to the current directory's name.
If \".\" is provided, the current directory name will be used regardless of whether a path was provided to uv venv.
--python, -p pythonThe Python interpreter to use for the virtual environment.
During virtual environment creation, uv will not look for Python interpreters in virtual environments.
See uv python for details on Python discovery and supported request formats.
May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--refreshRefresh all cached data
--refresh-package refresh-packageRefresh cached data for a specific package
--relocatableMake the virtual environment relocatable.
A relocatable virtual environment can be moved around and redistributed without invalidating its associated entrypoint and activation scripts.
Note that this can only be guaranteed for standard console_scripts and gui_scripts. Other scripts may be adjusted if they ship with a generic #!python[w] shebang, and binaries are left as-is.
As a result of making the environment relocatable (by way of writing relative, rather than absolute paths), the entrypoints and scripts themselves will not be relocatable. In other words, copying those entrypoints and scripts to a location outside the environment will not work, as they reference paths relative to the environment itself.
--seedInstall seed packages (one or more of: pip, setuptools, and wheel) into the virtual environment.
Note that setuptools and wheel are not included in Python 3.12+ environments.
May also be set with the UV_VENV_SEED environment variable.
--system-site-packagesGive the virtual environment access to the system site packages directory.
Unlike pip, when a virtual environment is created with --system-site-packages, uv will not take system site packages into account when running commands like uv pip list or uv pip install. The --system-site-packages flag will provide the virtual environment with access to the system site packages directory at runtime, but will not affect the behavior of uv commands.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-build","level":2,"title":"uv build","text":"Build Python packages into source distributions and wheels.
uv build accepts a path to a directory or source distribution, which defaults to the current working directory.
By default, if passed a directory, uv build will build a source distribution (\"sdist\") from the source directory, and a binary distribution (\"wheel\") from the source distribution.
uv build --sdist can be used to build only the source distribution, uv build --wheel can be used to build only the binary distribution, and uv build --sdist --wheel can be used to build both distributions from source.
If passed a source distribution, uv build --wheel will build a wheel from the source distribution.
Usage uv build [OPTIONS] [SRC]\n
Arguments SRCThe directory from which distributions should be built, or a source distribution archive to build into a wheel.
Defaults to the current working directory.
Options --all-packages, --allBuilds all packages in the workspace.
The workspace will be discovered from the provided source directory, or the current directory if no source directory is provided.
If the workspace member does not exist, uv will exit with an error.
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--build-constraints, --build-constraint, -b build-constraintsConstrain build dependencies using the given requirements files when building distributions.
Constraints files are requirements.txt-like files that only control the version of a build dependency that's installed. However, including a package in a constraints file will not trigger the inclusion of that package on its own.
May also be set with the UV_BUILD_CONSTRAINT environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--clearClear the output directory before the build, removing stale artifacts
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--config-setting, --config-settings, -C config-settingSettings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs
--config-settings-package, --config-settings-package config-settings-packageSettings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs
--default-index default-indexThe URL of the default 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 given by this flag is given lower priority than all other indexes specified via the --index flag.
May also be set with the UV_DEFAULT_INDEX environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--exclude-newer exclude-newerLimit candidate packages to those that were uploaded prior to the given date.
Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.
May also be set with the UV_EXCLUDE_NEWER environment variable.
--exclude-newer-package exclude-newer-packageLimit candidate packages for a specific package to those that were uploaded prior to the given date.
Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z) or local date (e.g., 2006-12-02) in your system's configured time zone.
Can be provided multiple times for different packages.
--extra-index-url extra-index-url(Deprecated: use --index instead) 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.
May also be set with the UV_EXTRA_INDEX_URL environment variable.
--find-links, -f find-linksLocations 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.
May also be set with the UV_FIND_LINKS environment variable.
--force-pep517Always build through PEP 517, don't use the fast path for the uv build backend.
By default, uv won't create a PEP 517 build environment for packages using the uv build backend, but use a fast path that calls into the build backend directly. This option forces always using PEP 517.
--fork-strategy fork-strategyThe 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.
May also be set with the UV_FORK_STRATEGY environment variable.
Possible values:
fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platformsrequires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--help, -hDisplay the concise help for this command
--index indexThe URLs to use when resolving dependencies, in addition to the default index.
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 --default-index (which defaults to PyPI). When multiple --index flags are provided, earlier values take priority.
Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\\\, ..\\\\, ./ or ../ on Windows.
May also be set with the UV_INDEX environment variable.
--index-strategy index-strategyThe 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.
May also be set with the UV_INDEX_STRATEGY environment variable.
Possible values:
first-index: Only use results from the first index that returns a match for a given package nameunsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the nextunsafe-best-match: Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
--index-url, -i index-url(Deprecated: use --default-index instead) 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.
May also be set with the UV_INDEX_URL environment variable.
--keyring-provider keyring-providerAttempt 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.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--link-mode link-modeThe method to use when installing packages from the global cache.
This option is only used when building source distributions.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
May also be set with the UV_LINK_MODE environment variable.
Possible values:
clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directorycopy: Copy packages from the wheel into the site-packages directoryhardlink: Hard link packages from the wheel into the site-packages directorysymlink: Symbolically link packages from the wheel into the site-packages directory
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-binaryDon'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.
May also be set with the UV_NO_BINARY environment variable.
--no-binary-package no-binary-packageDon't install pre-built wheels for a specific package
May also be set with the UV_NO_BINARY_PACKAGE environment variable.
--no-buildDon'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.
May also be set with the UV_NO_BUILD environment variable.
--no-build-isolationDisable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
May also be set with the UV_NO_BUILD_ISOLATION environment variable.
--no-build-isolation-package no-build-isolation-packageDisable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
--no-build-logsHide logs from the build backend
--no-build-package no-build-packageDon't build source distributions for a specific package
May also be set with the UV_NO_BUILD_PACKAGE environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-create-gitignoreDo not create a .gitignore file in the output directory.
By default, uv creates a .gitignore file in the output directory to exclude build artifacts from version control. When this flag is used, the file will be omitted.
--no-indexIgnore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--no-sourcesIgnore the tool.uv.sources table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path sources
May also be set with the UV_NO_SOURCES environment variable.
--no-verify-hashesDisable validation of hashes in the requirements file.
By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash. To enforce hash validation, use --require-hashes.
May also be set with the UV_NO_VERIFY_HASHES environment variable.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--out-dir, -o out-dirThe output directory to which distributions should be written.
Defaults to the dist subdirectory within the source directory, or the directory containing the source distribution archive.
--package packageBuild a specific package in the workspace.
The workspace will be discovered from the provided source directory, or the current directory if no source directory is provided.
If the workspace member does not exist, uv will exit with an error.
--prerelease prereleaseThe 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).
May also be set with the UV_PRERELEASE environment variable.
Possible values:
disallow: Disallow all pre-release versionsallow: Allow all pre-release versionsif-necessary: Allow pre-release versions if all versions of a package are pre-releaseexplicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirementsif-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--python, -p pythonThe Python interpreter to use for the build environment.
By default, builds are executed in isolated virtual environments. The discovered interpreter will be used to create those environments, and will be symlinked or copied in depending on the platform.
See uv python to view supported request formats.
May also be set with the UV_PYTHON environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--refreshRefresh all cached data
--refresh-package refresh-packageRefresh cached data for a specific package
--require-hashesRequire a matching hash for each requirement.
By default, uv will verify any available hashes in the requirements file, but will not require that all requirements have an associated hash.
When --require-hashes is enabled, all requirements must include a hash or set of hashes, and 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.
May also be set with the UV_REQUIRE_HASHES environment variable.
--resolution resolutionThe 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).
May also be set with the UV_RESOLUTION environment variable.
Possible values:
highest: Resolve the highest compatible version of each packagelowest: Resolve the lowest compatible version of each packagelowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--sdistBuild a source distribution (\"sdist\") from the given directory
--upgrade, -UAllow package upgrades, ignoring pinned versions in any existing output file. Implies --refresh
--upgrade-package, -P upgrade-packageAllow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies --refresh-package
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
--wheelBuild a binary distribution (\"wheel\") from the given directory
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-publish","level":2,"title":"uv publish","text":"Upload distributions to an index
Usage uv publish [OPTIONS] [FILES]...\n
Arguments FILESPaths to the files to upload. Accepts glob expressions.
Defaults to the dist directory. Selects only wheels and source distributions, while ignoring other files.
Options --allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--check-url check-urlCheck an index URL for existing files to skip duplicate uploads.
This option allows retrying publishing that failed after only some, but not all files have been uploaded, and handles errors due to parallel uploads of the same file.
Before uploading, the index is checked. If the exact same file already exists in the index, the file will not be uploaded. If an error occurred during the upload, the index is checked again, to handle cases where the identical file was uploaded twice in parallel.
The exact behavior will vary based on the index. When uploading to PyPI, uploading the same file succeeds even without --check-url, while most other indexes error. When uploading to pyx, the index URL can be inferred automatically from the publish URL.
The index must provide one of the supported hashes (SHA-256, SHA-384, or SHA-512).
May also be set with the UV_PUBLISH_CHECK_URL environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runPerform a dry run without uploading files.
When enabled, the command will check for existing files if --check-url is provided, and will perform validation against the index if supported, but will not upload any files.
--help, -hDisplay the concise help for this command
--index indexThe name of an index in the configuration to use for publishing.
The index must have a publish-url setting, for example:
[[tool.uv.index]]\nname = \"pypi\"\nurl = \"https://pypi.org/simple\"\npublish-url = \"https://upload.pypi.org/legacy/\"\n
The index url will be used to check for existing files to skip duplicate uploads.
With these settings, the following two calls are equivalent:
uv publish --index pypi\nuv publish --publish-url https://upload.pypi.org/legacy/ --check-url https://pypi.org/simple\n
May also be set with the UV_PUBLISH_INDEX environment variable.
--keyring-provider keyring-providerAttempt to use keyring for authentication for remote requirements files.
At present, only --keyring-provider subprocess is supported, which configures uv to use the keyring CLI to handle authentication.
Defaults to disabled.
May also be set with the UV_KEYRING_PROVIDER environment variable.
Possible values:
disabled: Do not use keyring for credential lookupsubprocess: Use the keyring command for credential lookup
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--password, -p passwordThe password for the upload
May also be set with the UV_PUBLISH_PASSWORD environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--publish-url publish-urlThe URL of the upload endpoint (not the index URL).
Note that there are typically different URLs for index access (e.g., https:://.../simple) and index upload.
Defaults to PyPI's publish URL (https://upload.pypi.org/legacy/).
May also be set with the UV_PUBLISH_URL environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--token, -t tokenThe token for the upload.
Using a token is equivalent to passing __token__ as --username and the token as --password password.
May also be set with the UV_PUBLISH_TOKEN environment variable.
--trusted-publishing trusted-publishingConfigure trusted publishing.
By default, uv checks for trusted publishing when running in a supported environment, but ignores it if it isn't configured.
uv's supported environments for trusted publishing include GitHub Actions and GitLab CI/CD.
Possible values:
automatic: Attempt trusted publishing when we're in a supported environment, continue if that failsalwaysnever
--username, -u usernameThe username for the upload
May also be set with the UV_PUBLISH_USERNAME environment variable.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-cache","level":2,"title":"uv cache","text":"Manage uv's cache
Usage uv cache [OPTIONS] <COMMAND>\n
Commands uv cache cleanClear the cache, removing all entries or those linked to specific packages
uv cache prunePrune all unreachable objects from the cache
uv cache dirShow the cache directory
uv cache sizeShow the cache size
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-cache-clean","level":3,"title":"uv cache cleanUsageArgumentsOptions","text":"Clear the cache, removing all entries or those linked to specific packages
uv cache clean [OPTIONS] [PACKAGE]...\n
PACKAGEThe packages to remove from the cache
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--forceForce removal of the cache, ignoring in-use checks.
By default, uv cache clean will block until no process is reading the cache. When --force is used, uv cache clean will proceed without taking a lock.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-cache-prune","level":3,"title":"uv cache pruneUsageOptions","text":"Prune all unreachable objects from the cache
uv cache prune [OPTIONS]\n
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--ciOptimize the cache for persistence in a continuous integration environment, like GitHub Actions.
By default, uv caches both the wheels that it builds from source and the pre-built wheels that it downloads directly, to enable high-performance package installation. In some scenarios, though, persisting pre-built wheels may be undesirable. For example, in GitHub Actions, it's faster to omit pre-built wheels from the cache and instead have re-download them on each run. However, it typically is faster to cache wheels that are built from source, since the wheel building process can be expensive, especially for extension modules.
In --ci mode, uv will prune any pre-built wheels from the cache, but retain any wheels that were built from source.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--forceForce removal of the cache, ignoring in-use checks.
By default, uv cache prune will block until no process is reading the cache. When --force is used, uv cache prune will proceed without taking a lock.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-cache-dir","level":3,"title":"uv cache dirUsageOptions","text":"Show the cache directory.
By default, the cache is stored in $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Unix and %LOCALAPPDATA%\\uv\\cache on Windows.
When --no-cache is used, the cache is stored in a temporary directory and discarded when the process exits.
An alternative cache directory may be specified via the cache-dir setting, the --cache-dir option, or the $UV_CACHE_DIR environment variable.
Note that it is important for performance for the cache directory to be located on the same file system as the Python environment uv is operating on.
uv cache dir [OPTIONS]\n
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-cache-size","level":3,"title":"uv cache sizeUsageOptions","text":"Show the cache size.
Displays the total size of the cache directory. This includes all downloaded and built wheels, source distributions, and other cached data. By default, outputs the size in raw bytes; use --human for human-readable output.
uv cache size [OPTIONS]\n
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--human, --human-readable, -HDisplay the cache size in human-readable format (e.g., 1.2 GiB instead of raw bytes)
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-self","level":2,"title":"uv self","text":"Manage the uv executable
Usage uv self [OPTIONS] <COMMAND>\n
Commands uv self updateUpdate uv
uv self versionDisplay uv's version
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-self-update","level":3,"title":"uv self updateUsageArgumentsOptions","text":"Update uv
uv self update [OPTIONS] [TARGET_VERSION]\n
TARGET_VERSIONUpdate to the specified version. If not provided, uv will update to the latest version
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--dry-runRun without performing the update
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--token tokenA GitHub token for authentication. A token is not required but can be used to reduce the chance of encountering rate limits
May also be set with the UV_GITHUB_TOKEN environment variable.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-self-version","level":3,"title":"uv self versionUsageOptions","text":"Display uv's version
uv self version [OPTIONS]\n
--allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--output-format output-format--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--shortOnly print the version
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-generate-shell-completion","level":2,"title":"uv generate-shell-completion","text":"Generate shell completion
Usage uv generate-shell-completion [OPTIONS] <SHELL>\n
Arguments SHELLThe shell to generate the completion script for
Options --allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/cli/#uv-help","level":2,"title":"uv help","text":"Display documentation for a command
Usage uv help [OPTIONS] [COMMAND]...\n
Arguments COMMAND Options --allow-insecure-host, --trusted-host allow-insecure-hostAllow insecure connections to a host.
Can be provided multiple times.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
May also be set with the UV_INSECURE_HOST environment variable.
--cache-dir cache-dirPath to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\\uv\\cache on Windows.
To view the location of the cache directory, run uv cache dir.
May also be set with the UV_CACHE_DIR environment variable.
--color color-choiceControl the use of color in output.
By default, uv will automatically detect support for colors when writing to a terminal.
Possible values:
auto: Enables colored output only when the output is going to a terminal or TTY with supportalways: Enables colored output regardless of the detected environmentnever: Disables colored output
--config-file config-fileThe path to a uv.toml file to use for configuration.
While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.
May also be set with the UV_CONFIG_FILE environment variable.
--directory directoryChange to the given directory prior to running the command.
Relative paths are resolved with the given directory as the base.
See --project to only change the project root directory.
May also be set with the UV_WORKING_DIRECTORY environment variable.
--help, -hDisplay the concise help for this command
--managed-pythonRequire use of uv-managed Python versions.
By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.
May also be set with the UV_MANAGED_PYTHON environment variable.
--native-tlsWhether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
May also be set with the UV_NATIVE_TLS environment variable.
--no-cache, --no-cache-dir, -nAvoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
May also be set with the UV_NO_CACHE environment variable.
--no-configAvoid discovering configuration files (pyproject.toml, uv.toml).
Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
May also be set with the UV_NO_CONFIG environment variable.
--no-managed-pythonDisable use of uv-managed Python versions.
Instead, uv will search for a suitable Python version on the system.
May also be set with the UV_NO_MANAGED_PYTHON environment variable.
--no-pagerDisable pager when printing help
--no-progressHide all progress outputs.
For example, spinners or progress bars.
May also be set with the UV_NO_PROGRESS environment variable.
--no-python-downloadsDisable automatic downloads of Python.
--offlineDisable network access.
When disabled, uv will only use locally cached data and locally available files.
May also be set with the UV_OFFLINE environment variable.
--project projectRun the command within the given project directory.
All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).
Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
See --directory to change the working directory entirely.
This setting has no effect when used in the uv pip interface.
May also be set with the UV_PROJECT environment variable.
--quiet, -qUse quiet output.
Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.
--verbose, -vUse verbose output.
You can configure fine-grained logging using the RUST_LOG environment variable. (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)
","path":["Reference","CLI Reference"],"tags":[]},{"location":"reference/environment/","level":1,"title":"Environment variables","text":"uv defines and respects the following environment variables:
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_break_system_packages","level":3,"title":"UV_BREAK_SYSTEM_PACKAGES","text":"added in 0.1.32
Equivalent to the --break-system-packages command-line argument. If set to true, uv will allow the installation of packages that conflict with system-installed packages.
WARNING: UV_BREAK_SYSTEM_PACKAGES=true is intended for use in continuous integration (CI) or containerized environments and should be used with caution, as modifying the system Python can lead to unexpected behavior.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_build_constraint","level":3,"title":"UV_BUILD_CONSTRAINT","text":"added in 0.2.34
Equivalent to the --build-constraints command-line argument. If set, uv will use this file as constraints for any source distribution builds. Uses space-separated list of files.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_cache_dir","level":3,"title":"UV_CACHE_DIR","text":"added in 0.0.5
Equivalent to the --cache-dir command-line argument. If set, uv will use this directory for caching instead of the default cache directory.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_compile_bytecode","level":3,"title":"UV_COMPILE_BYTECODE","text":"added in 0.3.3
Equivalent to the --compile-bytecode command-line argument. If set, uv will compile Python source files to bytecode after installation.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_compile_bytecode_timeout","level":3,"title":"UV_COMPILE_BYTECODE_TIMEOUT","text":"added in 0.7.22
Timeout (in seconds) for bytecode compilation.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_concurrent_builds","level":3,"title":"UV_CONCURRENT_BUILDS","text":"added in 0.1.43
Sets the maximum number of source distributions that uv will build concurrently at any given time.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_concurrent_downloads","level":3,"title":"UV_CONCURRENT_DOWNLOADS","text":"added in 0.1.43
Sets the maximum number of in-flight concurrent downloads that uv will perform at any given time.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_concurrent_installs","level":3,"title":"UV_CONCURRENT_INSTALLS","text":"added in 0.1.45
Controls the number of threads used when installing and unzipping packages.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_config_file","level":3,"title":"UV_CONFIG_FILE","text":"added in 0.1.34
Equivalent to the --config-file command-line argument. Expects a path to a local uv.toml file to use as the configuration file.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_constraint","level":3,"title":"UV_CONSTRAINT","text":"added in 0.1.36
Equivalent to the --constraints command-line argument. If set, uv will use this file as the constraints file. Uses space-separated list of files.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_credentials_dir","level":3,"title":"UV_CREDENTIALS_DIR","text":"added in 0.8.15
The directory for storage of credentials when using a plain text backend.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_custom_compile_command","level":3,"title":"UV_CUSTOM_COMPILE_COMMAND","text":"added in 0.1.23
Equivalent to the --custom-compile-command command-line argument.
Used to override uv in the output header of the requirements.txt files generated by uv pip compile. Intended for use-cases in which uv pip compile is called from within a wrapper script, to include the name of the wrapper script in the output file.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_default_index","level":3,"title":"UV_DEFAULT_INDEX","text":"added in 0.4.23
Equivalent to the --default-index command-line argument. If set, uv will use this URL as the default index when searching for packages.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_dev","level":3,"title":"UV_DEV","text":"added in 0.8.7
Equivalent to the --dev command-line argument. If set, uv will include development dependencies.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_download_url","level":3,"title":"UV_DOWNLOAD_URL","text":"added in 0.8.4
The URL from which to download uv using the standalone installer. By default, installs from uv's GitHub Releases. INSTALLER_DOWNLOAD_URL is also supported as an alias, for backwards compatibility.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_env_file","level":3,"title":"UV_ENV_FILE","text":"added in 0.4.30
.env files from which to load environment variables when executing uv run commands.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_exclude","level":3,"title":"UV_EXCLUDE","text":"added in 0.9.8
Equivalent to the --excludes command-line argument. If set, uv will use this as the excludes file. Uses space-separated list of files.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_exclude_newer","level":3,"title":"UV_EXCLUDE_NEWER","text":"added in 0.2.12
Equivalent to the --exclude-newer command-line argument. If set, uv will exclude distributions published after the specified date.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_extra_index_url","level":3,"title":"UV_EXTRA_INDEX_URL","text":"added in 0.1.3
Equivalent to the --extra-index-url command-line argument. If set, uv will use this space-separated list of URLs as additional indexes when searching for packages. (Deprecated: use UV_INDEX instead.)
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_find_links","level":3,"title":"UV_FIND_LINKS","text":"added in 0.4.19
Equivalent to the --find-links command-line argument. If set, uv will use this comma-separated list of additional locations to search for packages.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_fork_strategy","level":3,"title":"UV_FORK_STRATEGY","text":"added in 0.5.9
Equivalent to the --fork-strategy argument. Controls version selection during universal resolution.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_frozen","level":3,"title":"UV_FROZEN","text":"added in 0.4.25
Equivalent to the --frozen command-line argument. If set, uv will run without updating the uv.lock file.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_github_token","level":3,"title":"UV_GITHUB_TOKEN","text":"added in 0.4.10
Equivalent to the --token argument for self update. A GitHub token for authentication.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_git_lfs","level":3,"title":"UV_GIT_LFS","text":"added in 0.5.19
Enables fetching files stored in Git LFS when installing a package from a Git repository.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_http_retries","level":3,"title":"UV_HTTP_RETRIES","text":"added in 0.7.21
The number of retries for HTTP requests. (default: 3)
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_http_timeout","level":3,"title":"UV_HTTP_TIMEOUT","text":"added in 0.1.7
Timeout (in seconds) for HTTP requests. (default: 30 s)
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_index","level":3,"title":"UV_INDEX","text":"added in 0.4.23
Equivalent to the --index command-line argument. If set, uv will use this space-separated list of URLs as additional indexes when searching for packages.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_index_strategy","level":3,"title":"UV_INDEX_STRATEGY","text":"added in 0.1.29
Equivalent to the --index-strategy command-line argument.
For example, if set to unsafe-best-match, uv will consider versions of a given package available across all index URLs, rather than limiting its search to the first index URL that contains the package.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_index_url","level":3,"title":"UV_INDEX_URL","text":"added in 0.0.5
Equivalent to the --index-url command-line argument. If set, uv will use this URL as the default index when searching for packages. (Deprecated: use UV_DEFAULT_INDEX instead.)
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_index_name_password","level":3,"title":"UV_INDEX_{name}_PASSWORD","text":"added in 0.4.23
Provides the HTTP Basic authentication password for a named index.
The name parameter is the name of the index. For example, given an index named foo, the environment variable key would be UV_INDEX_FOO_PASSWORD.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_index_name_username","level":3,"title":"UV_INDEX_{name}_USERNAME","text":"added in 0.4.23
Provides the HTTP Basic authentication username for a named index.
The name parameter is the name of the index. For example, given an index named foo, the environment variable key would be UV_INDEX_FOO_USERNAME.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_init_build_backend","level":3,"title":"UV_INIT_BUILD_BACKEND","text":"added in 0.8.2
Equivalent to the --build-backend argument for uv init. Determines the default backend to use when creating a new project.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_insecure_host","level":3,"title":"UV_INSECURE_HOST","text":"added in 0.3.5
Equivalent to the --allow-insecure-host argument.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_insecure_no_zip_validation","level":3,"title":"UV_INSECURE_NO_ZIP_VALIDATION","text":"added in 0.8.6
Disable ZIP validation for streamed wheels and ZIP-based source distributions.
WARNING: Disabling ZIP validation can expose your system to security risks by bypassing integrity checks and allowing uv to install potentially malicious ZIP files. If uv rejects a ZIP file due to failing validation, it is likely that the file is malformed; consider filing an issue with the package maintainer.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_installer_ghe_base_url","level":3,"title":"UV_INSTALLER_GHE_BASE_URL","text":"added in 0.5.0
The URL from which to download uv using the standalone installer and self update feature, in lieu of the default GitHub Enterprise URL.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_installer_github_base_url","level":3,"title":"UV_INSTALLER_GITHUB_BASE_URL","text":"added in 0.5.0
The URL from which to download uv using the standalone installer and self update feature, in lieu of the default GitHub URL.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_install_dir","level":3,"title":"UV_INSTALL_DIR","text":"added in 0.5.0
The directory in which to install uv using the standalone installer and self update feature. Defaults to ~/.local/bin.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_isolated","level":3,"title":"UV_ISOLATED","text":"added in 0.8.14
Equivalent to the --isolated command-line argument. If set, uv will avoid discovering a pyproject.toml or uv.toml file.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_keyring_provider","level":3,"title":"UV_KEYRING_PROVIDER","text":"added in 0.1.19
Equivalent to the --keyring-provider command-line argument. If set, uv will use this value as the keyring provider.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_libc","level":3,"title":"UV_LIBC","text":"added in 0.7.22
Overrides the environment-determined libc on linux systems when filling in the current platform within Python version requests. Options are: gnu, gnueabi, gnueabihf, musl, and none.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_link_mode","level":3,"title":"UV_LINK_MODE","text":"added in 0.1.40
Equivalent to the --link-mode command-line argument. If set, uv will use this as a link mode.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_locked","level":3,"title":"UV_LOCKED","text":"added in 0.4.25
Equivalent to the --locked command-line argument. If set, uv will assert that the uv.lock remains unchanged.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_log_context","level":3,"title":"UV_LOG_CONTEXT","text":"added in 0.6.4
Add additional context and structure to log messages.
If logging is not enabled, e.g., with RUST_LOG or -v, this has no effect.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_managed_python","level":3,"title":"UV_MANAGED_PYTHON","text":"added in 0.6.8
Require use of uv-managed Python versions.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_native_tls","level":3,"title":"UV_NATIVE_TLS","text":"added in 0.1.19
Equivalent to the --native-tls command-line argument. If set to true, uv will use the system's trust store instead of the bundled webpki-roots crate.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_binary","level":3,"title":"UV_NO_BINARY","text":"added in 0.5.30
Equivalent to the --no-binary command-line argument. If set, uv will install all packages from source. The resolver will still use pre-built wheels to extract package metadata, if available.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_binary_package","level":3,"title":"UV_NO_BINARY_PACKAGE","text":"added in 0.5.30
Equivalent to the --no-binary-package command line argument. If set, uv will not use pre-built wheels for the given space-delimited list of packages.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_build","level":3,"title":"UV_NO_BUILD","text":"added in 0.1.40
Equivalent to the --no-build command-line argument. If set, uv will not build source distributions.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_build_isolation","level":3,"title":"UV_NO_BUILD_ISOLATION","text":"added in 0.1.40
Equivalent to the --no-build-isolation command-line argument. If set, uv will skip isolation when building source distributions.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_build_package","level":3,"title":"UV_NO_BUILD_PACKAGE","text":"added in 0.6.5
Equivalent to the --no-build-package command line argument. If set, uv will not build source distributions for the given space-delimited list of packages.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_cache","level":3,"title":"UV_NO_CACHE","text":"added in 0.1.2
Equivalent to the --no-cache command-line argument. If set, uv will not use the cache for any operations.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_config","level":3,"title":"UV_NO_CONFIG","text":"added in 0.2.30
Equivalent to the --no-config command-line argument. If set, uv will not read any configuration files from the current directory, parent directories, or user configuration directories.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_dev","level":3,"title":"UV_NO_DEV","text":"added in 0.8.7
Equivalent to the --no-dev command-line argument. If set, uv will exclude development dependencies.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_editable","level":3,"title":"UV_NO_EDITABLE","text":"added in 0.6.15
Equivalent to the --no-editable command-line argument. If set, uv installs or exports any editable dependencies, including the project and any workspace members, as non-editable.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_env_file","level":3,"title":"UV_NO_ENV_FILE","text":"added in 0.4.30
Ignore .env files when executing uv run commands.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_github_fast_path","level":3,"title":"UV_NO_GITHUB_FAST_PATH","text":"added in 0.7.13
Disable GitHub-specific requests that allow uv to skip git fetch in some circumstances.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_group","level":3,"title":"UV_NO_GROUP","text":"added in 0.9.8
Equivalent to the --no-group command-line argument. If set, uv will disable the specified dependency groups for the given space-delimited list of packages.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_hf_token","level":3,"title":"UV_NO_HF_TOKEN","text":"added in 0.8.1
Disable Hugging Face authentication, even if HF_TOKEN is set.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_installer_metadata","level":3,"title":"UV_NO_INSTALLER_METADATA","text":"added in 0.5.7
Skip writing uv installer metadata files (e.g., INSTALLER, REQUESTED, and direct_url.json) to site-packages .dist-info directories.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_managed_python","level":3,"title":"UV_NO_MANAGED_PYTHON","text":"added in 0.6.8
Disable use of uv-managed Python versions.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_modify_path","level":3,"title":"UV_NO_MODIFY_PATH","text":"added in 0.8.4
Avoid modifying the PATH environment variable when installing uv using the standalone installer and self update feature. INSTALLER_NO_MODIFY_PATH is also supported as an alias, for backwards compatibility.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_progress","level":3,"title":"UV_NO_PROGRESS","text":"added in 0.2.28
Equivalent to the --no-progress command-line argument. Disables all progress output. For example, spinners and progress bars.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_sources","level":3,"title":"UV_NO_SOURCES","text":"added in 0.9.8
Equivalent to the --no-sources command-line argument. If set, uv will ignore [tool.uv.sources] annotations when resolving dependencies.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_sync","level":3,"title":"UV_NO_SYNC","text":"added in 0.4.18
Equivalent to the --no-sync command-line argument. If set, uv will skip updating the environment.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_verify_hashes","level":3,"title":"UV_NO_VERIFY_HASHES","text":"added in 0.5.3
Equivalent to the --no-verify-hashes argument. Disables hash verification for requirements.txt files.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_no_wrap","level":3,"title":"UV_NO_WRAP","text":"added in 0.0.5
Use to disable line wrapping for diagnostics.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_offline","level":3,"title":"UV_OFFLINE","text":"added in 0.5.9
Equivalent to the --offline command-line argument. If set, uv will disable network access.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_override","level":3,"title":"UV_OVERRIDE","text":"added in 0.2.22
Equivalent to the --overrides command-line argument. If set, uv will use this file as the overrides file. Uses space-separated list of files.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_prerelease","level":3,"title":"UV_PRERELEASE","text":"added in 0.1.16
Equivalent to the --prerelease command-line argument. For example, if set to allow, uv will allow pre-release versions for all dependencies.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_preview","level":3,"title":"UV_PREVIEW","text":"added in 0.1.37
Equivalent to the --preview argument. Enables preview mode.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_preview_features","level":3,"title":"UV_PREVIEW_FEATURES","text":"added in 0.8.4
Equivalent to the --preview-features argument. Enables specific preview features.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_project","level":3,"title":"UV_PROJECT","text":"added in 0.4.4
Equivalent to the --project command-line argument.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_project_environment","level":3,"title":"UV_PROJECT_ENVIRONMENT","text":"added in 0.4.4
Specifies the path to the directory to use for a project virtual environment.
See the project documentation for more details.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_publish_check_url","level":3,"title":"UV_PUBLISH_CHECK_URL","text":"added in 0.4.30
Don't upload a file if it already exists on the index. The value is the URL of the index.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_publish_index","level":3,"title":"UV_PUBLISH_INDEX","text":"added in 0.5.8
Equivalent to the --index command-line argument in uv publish. If set, uv the index with this name in the configuration for publishing.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_publish_password","level":3,"title":"UV_PUBLISH_PASSWORD","text":"added in 0.4.16
Equivalent to the --password command-line argument in uv publish. If set, uv will use this password for publishing.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_publish_token","level":3,"title":"UV_PUBLISH_TOKEN","text":"added in 0.4.16
Equivalent to the --token command-line argument in uv publish. If set, uv will use this token (with the username __token__) for publishing.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_publish_url","level":3,"title":"UV_PUBLISH_URL","text":"added in 0.4.16
Equivalent to the --publish-url command-line argument. The URL of the upload endpoint of the index to use with uv publish.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_publish_username","level":3,"title":"UV_PUBLISH_USERNAME","text":"added in 0.4.16
Equivalent to the --username command-line argument in uv publish. If set, uv will use this username for publishing.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_pypy_install_mirror","level":3,"title":"UV_PYPY_INSTALL_MIRROR","text":"added in 0.2.35
Managed PyPy installations are downloaded from python.org.
This variable can be set to a mirror URL to use a different source for PyPy installations. The provided URL will replace https://downloads.python.org/pypy in, e.g., https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2. Distributions can be read from a local directory by using the file:// URL scheme.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_python","level":3,"title":"UV_PYTHON","text":"added in 0.1.40
Equivalent to the --python command-line argument. If set to a path, uv will use this Python interpreter for all operations.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_python_bin_dir","level":3,"title":"UV_PYTHON_BIN_DIR","text":"added in 0.4.29
Specifies the directory to place links to installed, managed Python executables.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_python_cache_dir","level":3,"title":"UV_PYTHON_CACHE_DIR","text":"added in 0.7.0
Specifies the directory for caching the archives of managed Python installations before installation.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_python_cpython_build","level":3,"title":"UV_PYTHON_CPYTHON_BUILD","text":"added in 0.8.14
Pin managed CPython versions to a specific build version.
For CPython, this should be the build date (e.g., \"20250814\").
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_python_downloads","level":3,"title":"UV_PYTHON_DOWNLOADS","text":"added in 0.3.2
Equivalent to the python-downloads setting and, when disabled, the --no-python-downloads option. Whether uv should allow Python downloads.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_python_downloads_json_url","level":3,"title":"UV_PYTHON_DOWNLOADS_JSON_URL","text":"added in 0.6.13
Managed Python installations information is hardcoded in the uv binary.
This variable can be set to a URL pointing to JSON to use as a list for Python installations. This will allow for setting each property of the Python installation, mostly the url part for offline mirror.
Note that currently, only local paths are supported.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_python_graalpy_build","level":3,"title":"UV_PYTHON_GRAALPY_BUILD","text":"added in 0.8.14
Pin managed GraalPy versions to a specific build version.
For GraalPy, this should be the GraalPy version (e.g., \"24.2.2\").
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_python_install_bin","level":3,"title":"UV_PYTHON_INSTALL_BIN","text":"added in 0.8.0
Whether to install the Python executable into the UV_PYTHON_BIN_DIR directory.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_python_install_dir","level":3,"title":"UV_PYTHON_INSTALL_DIR","text":"added in 0.2.22
Specifies the directory for storing managed Python installations.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_python_install_mirror","level":3,"title":"UV_PYTHON_INSTALL_MIRROR","text":"added in 0.2.35
Managed Python installations are downloaded from the Astral python-build-standalone project.
This variable can be set to a mirror URL to use a different source for Python installations. The provided URL will replace https://github.com/astral-sh/python-build-standalone/releases/download in, e.g., https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz. Distributions can be read from a local directory by using the file:// URL scheme.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_python_install_registry","level":3,"title":"UV_PYTHON_INSTALL_REGISTRY","text":"added in 0.8.0
Whether to install the Python executable into the Windows registry.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_python_preference","level":3,"title":"UV_PYTHON_PREFERENCE","text":"added in 0.3.2
Whether uv should prefer system or managed Python versions.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_python_pyodide_build","level":3,"title":"UV_PYTHON_PYODIDE_BUILD","text":"added in 0.8.14
Pin managed Pyodide versions to a specific build version.
For Pyodide, this should be the Pyodide version (e.g., \"0.28.1\").
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_python_pypy_build","level":3,"title":"UV_PYTHON_PYPY_BUILD","text":"added in 0.8.14
Pin managed PyPy versions to a specific build version.
For PyPy, this should be the PyPy version (e.g., \"7.3.20\").
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_request_timeout","level":3,"title":"UV_REQUEST_TIMEOUT","text":"added in 0.1.6
Timeout (in seconds) for HTTP requests. Equivalent to UV_HTTP_TIMEOUT.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_require_hashes","level":3,"title":"UV_REQUIRE_HASHES","text":"added in 0.1.34
Equivalent to the --require-hashes command-line argument. If set to true, uv will require that all dependencies have a hash specified in the requirements file.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_resolution","level":3,"title":"UV_RESOLUTION","text":"added in 0.1.27
Equivalent to the --resolution command-line argument. For example, if set to lowest-direct, uv will install the lowest compatible versions of all direct dependencies.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_s3_endpoint_url","level":3,"title":"UV_S3_ENDPOINT_URL","text":"added in 0.8.21
The URL to treat as an S3-compatible storage endpoint. Requests to this endpoint will be signed using AWS Signature Version 4 based on the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_PROFILE, and AWS_CONFIG_FILE environment variables.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_skip_wheel_filename_check","level":3,"title":"UV_SKIP_WHEEL_FILENAME_CHECK","text":"added in 0.8.23
Avoid verifying that wheel filenames match their contents when installing wheels. This is not recommended, as wheels with inconsistent filenames should be considered invalid and corrected by the relevant package maintainers; however, this option can be used to work around invalid artifacts in rare cases.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_stack_size","level":3,"title":"UV_STACK_SIZE","text":"added in 0.0.5
Use to set the stack size used by uv.
The value is in bytes, and if both UV_STACK_SIZE are RUST_MIN_STACK unset, uv uses a 4MB (4194304) stack. UV_STACK_SIZE takes precedence over RUST_MIN_STACK.
Unlike the normal RUST_MIN_STACK semantics, this can affect main thread stack size, because we actually spawn our own main2 thread to work around the fact that Windows' real main thread is only 1MB. That thread has size max(UV_STACK_SIZE, 1MB).
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_system_python","level":3,"title":"UV_SYSTEM_PYTHON","text":"added in 0.1.18
Equivalent to the --system command-line argument. If set to true, uv will use the first Python interpreter found in the system PATH.
WARNING: UV_SYSTEM_PYTHON=true is intended for use in continuous integration (CI) or containerized environments and should be used with caution, as modifying the system Python can lead to unexpected behavior.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_test_no_http_retry_delay","level":3,"title":"UV_TEST_NO_HTTP_RETRY_DELAY","text":"added in 0.7.21
Used to disable delay for HTTP retries in tests.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_tool_bin_dir","level":3,"title":"UV_TOOL_BIN_DIR","text":"added in 0.3.0
Specifies the \"bin\" directory for installing tool executables.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_tool_dir","level":3,"title":"UV_TOOL_DIR","text":"added in 0.2.16
Specifies the directory where uv stores managed tools.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_torch_backend","level":3,"title":"UV_TORCH_BACKEND","text":"added in 0.6.9
Equivalent to the --torch-backend command-line argument (e.g., cpu, cu126, or auto).
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_unmanaged_install","level":3,"title":"UV_UNMANAGED_INSTALL","text":"added in 0.5.0
Used ephemeral environments like CI to install uv to a specific path while preventing the installer from modifying shell profiles or environment variables.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_upload_http_timeout","level":3,"title":"UV_UPLOAD_HTTP_TIMEOUT","text":"added in 0.9.1
Timeout (in seconds) for only upload HTTP requests. (default: 900 s)
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_venv_clear","level":3,"title":"UV_VENV_CLEAR","text":"added in 0.8.0
Equivalent to the --clear command-line argument. If set, uv will remove any existing files or directories at the target path.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_venv_seed","level":3,"title":"UV_VENV_SEED","text":"added in 0.5.21
Install seed packages (one or more of: pip, setuptools, and wheel) into the virtual environment created by uv venv.
Note that setuptools and wheel are not included in Python 3.12+ environments.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv_working_directory","level":3,"title":"UV_WORKING_DIRECTORY","text":"added in 0.9.1
Equivalent to the --directory command-line argument.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#externally-defined-variables","level":2,"title":"Externally defined variables","text":"uv also reads the following externally defined environment variables:
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#all_proxy","level":3,"title":"ALL_PROXY","text":"added in 0.1.38
General proxy for all network requests.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#android_api_level","level":3,"title":"ANDROID_API_LEVEL","text":"added in 0.8.16
Used with --python-platform aarch64-linux-android and related variants to set the Android API level. (i.e., the minimum supported Android API level).
Defaults to 24.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#appdata","level":3,"title":"APPDATA","text":"added in 0.1.42
Path to user-level configuration directory on Windows systems.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#aws_access_key_id","level":3,"title":"AWS_ACCESS_KEY_ID","text":"added in 0.8.21
The AWS access key ID to use when signing S3 requests.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#aws_config_file","level":3,"title":"AWS_CONFIG_FILE","text":"added in 0.8.21
The AWS config file to use when signing S3 requests.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#aws_default_region","level":3,"title":"AWS_DEFAULT_REGION","text":"added in 0.8.21
The default AWS region to use when signing S3 requests, if AWS_REGION is not set.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#aws_profile","level":3,"title":"AWS_PROFILE","text":"added in 0.8.21
The AWS profile to use when signing S3 requests.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#aws_region","level":3,"title":"AWS_REGION","text":"added in 0.8.21
The AWS region to use when signing S3 requests.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#aws_secret_access_key","level":3,"title":"AWS_SECRET_ACCESS_KEY","text":"added in 0.8.21
The AWS secret access key to use when signing S3 requests.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#aws_session_token","level":3,"title":"AWS_SESSION_TOKEN","text":"added in 0.8.21
The AWS session token to use when signing S3 requests.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#aws_shared_credentials_file","level":3,"title":"AWS_SHARED_CREDENTIALS_FILE","text":"added in 0.8.21
The AWS shared credentials file to use when signing S3 requests.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#bash_version","level":3,"title":"BASH_VERSION","text":"added in 0.1.28
Used to detect Bash shell usage.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#clicolor_force","level":3,"title":"CLICOLOR_FORCE","text":"added in 0.1.32
Use to control color via anstyle.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#columns","level":3,"title":"COLUMNS","text":"added in 0.6.2
Overrides terminal width used for wrapping. This variable is not read by uv directly.
This is a quasi-standard variable, described, e.g., in ncurses(3x).
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#conda_default_env","level":3,"title":"CONDA_DEFAULT_ENV","text":"added in 0.5.0
Used to determine the name of the active Conda environment.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#conda_prefix","level":3,"title":"CONDA_PREFIX","text":"added in 0.0.5
Used to detect the path of an active Conda environment.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#fish_version","level":3,"title":"FISH_VERSION","text":"added in 0.1.28
Used to detect Fish shell usage.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#force_color","level":3,"title":"FORCE_COLOR","text":"added in 0.2.7
Forces colored output regardless of terminal support.
See force-color.org.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#github_actions","level":3,"title":"GITHUB_ACTIONS","text":"added in 0.4.16
Indicates that the current process is running in GitHub Actions.
uv publish may attempt trusted publishing flows when set to true.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#gitlab_ci","level":3,"title":"GITLAB_CI","text":"added in 0.8.18
Indicates that the current process is running in GitLab CI.
uv publish may attempt trusted publishing flows when set to true.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#hf_token","level":3,"title":"HF_TOKEN","text":"added in 0.8.1
Authentication token for Hugging Face requests. When set, uv will use this token when making requests to https://huggingface.co/ and any subdomains.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#home","level":3,"title":"HOME","text":"added in 0.0.5
The standard HOME env var.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#https_proxy","level":3,"title":"HTTPS_PROXY","text":"added in 0.1.38
Proxy for HTTPS requests.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#http_proxy","level":3,"title":"HTTP_PROXY","text":"added in 0.1.38
Proxy for HTTP requests.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#http_timeout","level":3,"title":"HTTP_TIMEOUT","text":"added in 0.1.7
Timeout (in seconds) for HTTP requests. Equivalent to UV_HTTP_TIMEOUT.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#iphoneos_deployment_target","level":3,"title":"IPHONEOS_DEPLOYMENT_TARGET","text":"added in 0.8.16
Used with --python-platform arm64-apple-ios and related variants to set the deployment target (i.e., the minimum supported iOS version).
Defaults to 13.0.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#jpy_session_name","level":3,"title":"JPY_SESSION_NAME","text":"added in 0.2.6
Used to detect when running inside a Jupyter notebook.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#ksh_version","level":3,"title":"KSH_VERSION","text":"added in 0.2.33
Used to detect Ksh shell usage.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#localappdata","level":3,"title":"LOCALAPPDATA","text":"added in 0.3.3
Used to look for Microsoft Store Pythons installations.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#macosx_deployment_target","level":3,"title":"MACOSX_DEPLOYMENT_TARGET","text":"added in 0.1.42
Used with --python-platform macos and related variants to set the deployment target (i.e., the minimum supported macOS version).
Defaults to 13.0, the least-recent non-EOL macOS version at time of writing.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#netrc","level":3,"title":"NETRC","text":"added in 0.1.16
Use to set the .netrc file location.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#no_color","level":3,"title":"NO_COLOR","text":"added in 0.2.7
Disables colored output (takes precedence over FORCE_COLOR).
See no-color.org.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#no_proxy","level":3,"title":"NO_PROXY","text":"added in 0.1.38
Comma-separated list of hostnames (e.g., example.com) and/or patterns (e.g., 192.168.1.0/24) that should bypass the proxy.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#nu_version","level":3,"title":"NU_VERSION","text":"added in 0.1.16
Used to detect NuShell usage.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#pager","level":3,"title":"PAGER","text":"added in 0.4.18
The standard PAGER posix env var. Used by uv to configure the appropriate pager.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#path","level":3,"title":"PATH","text":"added in 0.0.5
The standard PATH env var.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#prompt","level":3,"title":"PROMPT","text":"added in 0.1.16
Used to detect the use of the Windows Command Prompt (as opposed to PowerShell).
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#pwd","level":3,"title":"PWD","text":"added in 0.0.5
The standard PWD posix env var.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#pyc_invalidation_mode","level":3,"title":"PYC_INVALIDATION_MODE","text":"added in 0.1.7
The validation modes to use when run with --compile.
See PycInvalidationMode.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#pythonpath","level":3,"title":"PYTHONPATH","text":"added in 0.1.22
Adds directories to Python module search path (e.g., PYTHONPATH=/path/to/modules).
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#pyx_api_key","level":3,"title":"PYX_API_KEY","text":"added in 0.8.15
The pyx API key (e.g., sk-pyx-...).
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#pyx_api_url","level":3,"title":"PYX_API_URL","text":"added in 0.8.15
The URL of the pyx Simple API server.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#pyx_auth_token","level":3,"title":"PYX_AUTH_TOKEN","text":"added in 0.8.15
The pyx authentication token (e.g., eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...), as output by uv auth token.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#pyx_cdn_domain","level":3,"title":"PYX_CDN_DOMAIN","text":"added in 0.8.15
The domain of the pyx CDN.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#pyx_credentials_dir","level":3,"title":"PYX_CREDENTIALS_DIR","text":"added in 0.8.15
Specifies the directory where uv stores pyx credentials.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#rust_backtrace","level":3,"title":"RUST_BACKTRACE","text":"added in 0.7.22
If set, it can be used to display more stack trace details when a panic occurs. This is used by uv particularly on windows to show more details during a platform exception.
For example:
RUST_BACKTRACE=1 will print a short backtrace.RUST_BACKTRACE=full will print a full backtrace.
See the Rust backtrace documentation for more.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#rust_log","level":3,"title":"RUST_LOG","text":"added in 0.0.5
If set, uv will use this value as the log level for its --verbose output. Accepts any filter compatible with the tracing_subscriber crate.
For example:
RUST_LOG=uv=debug is the equivalent of adding --verbose to the command lineRUST_LOG=trace will enable trace-level logging.
See the tracing documentation for more.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#rust_min_stack","level":3,"title":"RUST_MIN_STACK","text":"added in 0.5.19
Use to set the stack size used by uv.
The value is in bytes, and if both UV_STACK_SIZE are RUST_MIN_STACK unset, uv uses a 4MB (4194304) stack. UV_STACK_SIZE takes precedence over RUST_MIN_STACK.
Prefer setting UV_STACK_SIZE, since RUST_MIN_STACK also affects subprocesses, such as build backends that use Rust code.
Unlike the normal RUST_MIN_STACK semantics, this can affect main thread stack size, because we actually spawn our own main2 thread to work around the fact that Windows' real main thread is only 1MB. That thread has size max(RUST_MIN_STACK, 1MB).
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#shell","level":3,"title":"SHELL","text":"added in 0.1.16
The standard SHELL posix env var.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#ssl_cert_file","level":3,"title":"SSL_CERT_FILE","text":"added in 0.1.14
Custom certificate bundle file path for SSL connections.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#ssl_client_cert","level":3,"title":"SSL_CLIENT_CERT","text":"added in 0.2.11
If set, uv will use this file for mTLS authentication. This should be a single file containing both the certificate and the private key in PEM format.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#systemdrive","level":3,"title":"SYSTEMDRIVE","text":"added in 0.4.26
Path to system-level configuration directory on Windows systems.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#tracing_durations_file","level":3,"title":"TRACING_DURATIONS_FILE","text":"added in 0.0.5
Use to create the tracing durations file via the tracing-durations-export feature.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#userprofile","level":3,"title":"USERPROFILE","text":"added in 0.0.5
Path to root directory of user's profile on Windows systems.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#uv","level":3,"title":"UV","text":"added in 0.6.0
The path to the binary that was used to invoke uv.
This is propagated to all subprocesses spawned by uv.
If the executable was invoked through a symbolic link, some platforms will return the path of the symbolic link and other platforms will return the path of the symbolic link’s target.
See https://doc.rust-lang.org/std/env/fn.current_exe.html#security for security considerations.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#virtual_env","level":3,"title":"VIRTUAL_ENV","text":"added in 0.0.5
Used to detect an activated virtual environment.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#virtual_env_disable_prompt","level":3,"title":"VIRTUAL_ENV_DISABLE_PROMPT","text":"added in 0.0.5
If set to 1 before a virtual environment is activated, then the virtual environment name will not be prepended to the terminal prompt.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#xdg_bin_home","level":3,"title":"XDG_BIN_HOME","text":"added in 0.2.16
Path to directory where executables are installed.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#xdg_cache_home","level":3,"title":"XDG_CACHE_HOME","text":"added in 0.1.17
Path to cache directory on Unix systems.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#xdg_config_dirs","level":3,"title":"XDG_CONFIG_DIRS","text":"added in 0.4.26
Path to system-level configuration directory on Unix systems.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#xdg_config_home","level":3,"title":"XDG_CONFIG_HOME","text":"added in 0.1.34
Path to user-level configuration directory on Unix systems.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#xdg_data_home","level":3,"title":"XDG_DATA_HOME","text":"added in 0.2.16
Path to directory for storing managed Python installations and tools.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#zdotdir","level":3,"title":"ZDOTDIR","text":"added in 0.2.25
Used to determine which .zshenv to use when Zsh is being used.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#zsh_version","level":3,"title":"ZSH_VERSION","text":"added in 0.1.28
Used to detect Zsh shell usage.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/environment/#_conda_root","level":3,"title":"_CONDA_ROOT","text":"added in 0.8.18
Used to determine the root install path of Conda.
","path":["Reference","Environment variables"],"tags":[]},{"location":"reference/installer/","level":1,"title":"The uv installer","text":"","path":["Reference","The uv installer"],"tags":[]},{"location":"reference/installer/#changing-the-installation-path","level":2,"title":"Changing the installation path","text":"By default, uv is installed to ~/.local/bin. If XDG_BIN_HOME is set, it will be used instead. Similarly, if XDG_DATA_HOME is set, the target directory will be inferred as XDG_DATA_HOME/../bin.
To change the installation path, use UV_INSTALL_DIR:
macOS and LinuxWindows $ curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=\"/custom/path\" sh\n
PS> powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR = \"C:\\Custom\\Path\";irm https://astral.sh/uv/install.ps1 | iex}\n
","path":["Reference","The uv installer"],"tags":[]},{"location":"reference/installer/#disabling-shell-modifications","level":2,"title":"Disabling shell modifications","text":"The installer may also update your shell profiles to ensure the uv binary is on your PATH. To disable this behavior, use UV_NO_MODIFY_PATH. For example:
$ curl -LsSf https://astral.sh/uv/install.sh | env UV_NO_MODIFY_PATH=1 sh\n
If installed with UV_NO_MODIFY_PATH, subsequent operations, like uv self update, will not modify your shell profiles.
","path":["Reference","The uv installer"],"tags":[]},{"location":"reference/installer/#unmanaged-installations","level":2,"title":"Unmanaged installations","text":"In ephemeral environments like CI, use UV_UNMANAGED_INSTALL to install uv to a specific path while preventing the installer from modifying shell profiles or environment variables:
$ curl -LsSf https://astral.sh/uv/install.sh | env UV_UNMANAGED_INSTALL=\"/custom/path\" sh\n
The use of UV_UNMANAGED_INSTALL will also disable self-updates (via uv self update).
","path":["Reference","The uv installer"],"tags":[]},{"location":"reference/installer/#passing-options-to-the-installation-script","level":2,"title":"Passing options to the installation script","text":"Using environment variables is recommended because they are consistent across platforms. However, options can be passed directly to the installation script. For example, to see the available options:
$ curl -LsSf https://astral.sh/uv/install.sh | sh -s -- --help\n
","path":["Reference","The uv installer"],"tags":[]},{"location":"reference/settings/","level":1,"title":"Settings","text":"","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#project-metadata","level":2,"title":"Project metadata","text":"","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#build-constraint-dependencies","level":3,"title":"build-constraint-dependencies","text":"Constraints to apply when solving build dependencies.
Build constraints are used to restrict the versions of build dependencies that are selected when building a package during resolution or installation.
Including a package as a constraint will not trigger installation of the package during a build; instead, the package must be requested elsewhere in the project's build dependency graph.
Note
In uv lock, uv sync, and uv run, uv will only read build-constraint-dependencies from the pyproject.toml at the workspace root, and will ignore any declarations in other workspace members or uv.toml files.
Default value: []
Type: list[str]
Example usage:
pyproject.toml[tool.uv]\n# Ensure that the setuptools v60.0.0 is used whenever a package has a build dependency\n# on setuptools.\nbuild-constraint-dependencies = [\"setuptools==60.0.0\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#conflicts","level":3,"title":"conflicts","text":"Declare collections of extras or dependency groups that are conflicting (i.e., mutually exclusive).
It's useful to declare conflicts when two or more extras have mutually incompatible dependencies. For example, extra foo might depend on numpy==2.0.0 while extra bar depends on numpy==2.1.0. While these dependencies conflict, it may be the case that users are not expected to activate both foo and bar at the same time, making it possible to generate a universal resolution for the project despite the incompatibility.
By making such conflicts explicit, uv can generate a universal resolution for a project, taking into account that certain combinations of extras and groups are mutually exclusive. In exchange, installation will fail if a user attempts to activate both conflicting extras.
Default value: []
Type: list[list[dict]]
Example usage:
pyproject.toml[tool.uv]\n# Require that `package[extra1]` and `package[extra2]` are resolved\n# in different forks so that they cannot conflict with one another.\nconflicts = [\n [\n { extra = \"extra1\" },\n { extra = \"extra2\" },\n ]\n]\n\n# Require that the dependency groups `group1` and `group2`\n# are resolved in different forks so that they cannot conflict\n# with one another.\nconflicts = [\n [\n { group = \"group1\" },\n { group = \"group2\" },\n ]\n]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#constraint-dependencies","level":3,"title":"constraint-dependencies","text":"Constraints to apply when resolving the project's dependencies.
Constraints are used to restrict the versions of dependencies that are selected during resolution.
Including a package as a constraint will not trigger installation of the package on its own; instead, the package must be requested elsewhere in the project's first-party or transitive dependencies.
Note
In uv lock, uv sync, and uv run, uv will only read constraint-dependencies from the pyproject.toml at the workspace root, and will ignore any declarations in other workspace members or uv.toml files.
Default value: []
Type: list[str]
Example usage:
pyproject.toml[tool.uv]\n# Ensure that the grpcio version is always less than 1.65, if it's requested by a\n# direct or transitive dependency.\nconstraint-dependencies = [\"grpcio<1.65\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#default-groups","level":3,"title":"default-groups","text":"The list of dependency-groups to install by default.
Can also be the literal \"all\" to default enable all groups.
Default value: [\"dev\"]
Type: str | list[str]
Example usage:
pyproject.toml[tool.uv]\ndefault-groups = [\"docs\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#dependency-groups","level":3,"title":"dependency-groups","text":"Additional settings for dependency-groups.
Currently this can only be used to add requires-python constraints to dependency groups (typically to inform uv that your dev tooling has a higher python requirement than your actual project).
This cannot be used to define dependency groups, use the top-level [dependency-groups] table for that.
Default value: []
Type: dict
Example usage:
pyproject.toml[tool.uv.dependency-groups]\nmy-group = {requires-python = \">=3.12\"}\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#dev-dependencies","level":3,"title":"dev-dependencies","text":"The project's development dependencies.
Development dependencies will be installed by default in uv run and uv sync, but will not appear in the project's published metadata.
Use of this field is not recommend anymore. Instead, use the dependency-groups.dev field which is a standardized way to declare development dependencies. The contents of tool.uv.dev-dependencies and dependency-groups.dev are combined to determine the final requirements of the dev dependency group.
Default value: []
Type: list[str]
Example usage:
pyproject.toml[tool.uv]\ndev-dependencies = [\"ruff==0.5.0\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#environments","level":3,"title":"environments","text":"A list of supported environments against which to resolve dependencies.
By default, uv will resolve for all possible environments during a uv lock operation. However, you can restrict the set of supported environments to improve performance and avoid unsatisfiable branches in the solution space.
These environments will also be respected when uv pip compile is invoked with the --universal flag.
Default value: []
Type: str | list[str]
Example usage:
pyproject.toml[tool.uv]\n# Resolve for macOS, but not for Linux or Windows.\nenvironments = [\"sys_platform == 'darwin'\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#exclude-dependencies","level":3,"title":"exclude-dependencies","text":"Dependencies to exclude when resolving the project's dependencies.
Excludes are used to prevent a package from being selected during resolution, regardless of whether it's requested by any other package. When a package is excluded, it will be omitted from the dependency list entirely.
Including a package as an exclusion will prevent it from being installed, even if it's requested by transitive dependencies. This can be useful for removing optional dependencies or working around packages with broken dependencies.
Note
In uv lock, uv sync, and uv run, uv will only read exclude-dependencies from the pyproject.toml at the workspace root, and will ignore any declarations in other workspace members or uv.toml files.
Default value: []
Type: list[str]
Example usage:
pyproject.toml[tool.uv]\n# Exclude Werkzeug from being installed, even if transitive dependencies request it.\nexclude-dependencies = [\"werkzeug\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#index","level":3,"title":"index","text":"The indexes to use when resolving dependencies.
Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.
Indexes are considered in the order in which they're defined, such that the first-defined index has the highest priority. Further, the indexes provided by this setting are given higher priority than any indexes specified via index_url or extra_index_url. uv will only consider the first index that contains a given package, unless an alternative index strategy is specified.
If an index is marked as explicit = true, it will be used exclusively for the dependencies that select it explicitly via [tool.uv.sources], as in:
[[tool.uv.index]]\nname = \"pytorch\"\nurl = \"https://download.pytorch.org/whl/cu121\"\nexplicit = true\n\n[tool.uv.sources]\ntorch = { index = \"pytorch\" }\n
If an index is marked as default = true, it will be moved to the end of the prioritized list, such that it is given the lowest priority when resolving packages. Additionally, marking an index as default will disable the PyPI default index.
Default value: []
Type: dict
Example usage:
pyproject.toml[[tool.uv.index]]\nname = \"pytorch\"\nurl = \"https://download.pytorch.org/whl/cu121\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#managed","level":3,"title":"managed","text":"Whether the project is managed by uv. If false, uv will ignore the project when uv run is invoked.
Default value: true
Type: bool
Example usage:
pyproject.toml[tool.uv]\nmanaged = false\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#override-dependencies","level":3,"title":"override-dependencies","text":"Overrides to apply when resolving the project's dependencies.
Overrides are used to force selection of a specific version of a package, regardless of the version requested by any other package, and regardless of whether choosing that version would typically constitute an invalid resolution.
While constraints are additive, in that they're combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of any constituent packages.
Including a package as an override will not trigger installation of the package on its own; instead, the package must be requested elsewhere in the project's first-party or transitive dependencies.
Note
In uv lock, uv sync, and uv run, uv will only read override-dependencies from the pyproject.toml at the workspace root, and will ignore any declarations in other workspace members or uv.toml files.
Default value: []
Type: list[str]
Example usage:
pyproject.toml[tool.uv]\n# Always install Werkzeug 2.3.0, regardless of whether transitive dependencies request\n# a different version.\noverride-dependencies = [\"werkzeug==2.3.0\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#package","level":3,"title":"package","text":"Whether the project should be considered a Python package, or a non-package (\"virtual\") project.
Packages are built and installed into the virtual environment in editable mode and thus require a build backend, while virtual projects are not built or installed; instead, only their dependencies are included in the virtual environment.
Creating a package requires that a build-system is present in the pyproject.toml, and that the project adheres to a structure that adheres to the build backend's expectations (e.g., a src layout).
Default value: true
Type: bool
Example usage:
pyproject.toml[tool.uv]\npackage = false\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#required-environments","level":3,"title":"required-environments","text":"A list of required platforms, for packages that lack source distributions.
When a package does not have a source distribution, it's availability will be limited to the platforms supported by its built distributions (wheels). For example, if a package only publishes wheels for Linux, then it won't be installable on macOS or Windows.
By default, uv requires each package to include at least one wheel that is compatible with the designated Python version. The required-environments setting can be used to ensure that the resulting resolution contains wheels for specific platforms, or fails if no such wheels are available.
While the environments setting limits the set of environments that uv will consider when resolving dependencies, required-environments expands the set of platforms that uv must support when resolving dependencies.
For example, environments = [\"sys_platform == 'darwin'\"] would limit uv to solving for macOS (and ignoring Linux and Windows). On the other hand, required-environments = [\"sys_platform == 'darwin'\"] would require that any package without a source distribution include a wheel for macOS in order to be installable.
Default value: []
Type: str | list[str]
Example usage:
pyproject.toml[tool.uv]\n# Require that the package is available for macOS ARM and x86 (Intel).\nrequired-environments = [\n \"sys_platform == 'darwin' and platform_machine == 'arm64'\",\n \"sys_platform == 'darwin' and platform_machine == 'x86_64'\",\n]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#sources","level":3,"title":"sources","text":"The sources to use when resolving dependencies.
tool.uv.sources enriches the dependency metadata with additional sources, incorporated during development. A dependency source can be a Git repository, a URL, a local path, or an alternative registry.
See Dependencies for more.
Default value: {}
Type: dict
Example usage:
pyproject.toml[tool.uv.sources]\nhttpx = { git = \"https://github.com/encode/httpx\", tag = \"0.27.0\" }\npytest = { url = \"https://files.pythonhosted.org/packages/6b/77/7440a06a8ead44c7757a64362dd22df5760f9b12dc5f11b6188cd2fc27a0/pytest-8.3.3-py3-none-any.whl\" }\npydantic = { path = \"/path/to/pydantic\", editable = true }\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#build-backend","level":3,"title":"build-backend","text":"Settings for the uv build backend (uv_build).
Note that those settings only apply when using the uv_build backend, other build backends (such as hatchling) have their own configuration.
All options that accept globs use the portable glob patterns from PEP 639.
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#build-backend_data","level":4,"title":"data","text":"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.
Default value: {}
Type: dict[str, str]
Example usage:
pyproject.toml[tool.uv.build-backend]\ndata = { headers = \"include/headers\", scripts = \"bin\" }\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#build-backend_default-excludes","level":4,"title":"default-excludes","text":"If set to false, the default excludes aren't applied.
Default excludes: __pycache__, *.pyc, and *.pyo.
Default value: true
Type: bool
Example usage:
pyproject.toml[tool.uv.build-backend]\ndefault-excludes = false\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#build-backend_module-name","level":4,"title":"module-name","text":"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.
Default value: None
Type: str | list[str]
Example usage:
pyproject.toml[tool.uv.build-backend]\nmodule-name = \"sklearn\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#build-backend_module-root","level":4,"title":"module-root","text":"The directory that contains the module directory.
Common values are src (src layout, the default) or an empty path (flat layout).
Default value: \"src\"
Type: str
Example usage:
pyproject.toml[tool.uv.build-backend]\nmodule-root = \"\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#build-backend_namespace","level":4,"title":"namespace","text":"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\n└── cloud\n └── database\n ├── __init__.py\n ├── query_builder\n │ └── __init__.py\n └── sql\n ├── parser.py\n └── __init__.py\n
src\n├── cloud\n│ ├── database\n│ │ ├── __init__.py\n│ │ ├── query_builder\n│ │ │ └── __init__.py\n│ │ └── sql\n│ │ ├── __init__.py\n│ │ └── parser.py\n│ └── database_pro\n│ ├── __init__.py\n│ └── query_builder.py\n└── billing\n └── modules\n └── database_pro\n ├── __init__.py\n └── sql.py\n
Default value: false
Type: bool
Example usage:
pyproject.toml[tool.uv.build-backend]\nnamespace = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#build-backend_source-exclude","level":4,"title":"source-exclude","text":"Glob expressions which files and directories to exclude from the source distribution.
Default value: []
Type: list[str]
Example usage:
pyproject.toml[tool.uv.build-backend]\nsource-exclude = [\"*.bin\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#build-backend_source-include","level":4,"title":"source-include","text":"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.
Default value: []
Type: list[str]
Example usage:
pyproject.toml[tool.uv.build-backend]\nsource-include = [\"tests/**\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#build-backend_wheel-exclude","level":4,"title":"wheel-exclude","text":"Glob expressions which files and directories to exclude from the wheel.
Default value: []
Type: list[str]
Example usage:
pyproject.toml[tool.uv.build-backend]\nwheel-exclude = [\"*.bin\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#workspace","level":3,"title":"workspace","text":"","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#workspace_exclude","level":4,"title":"exclude","text":"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.
Default value: []
Type: list[str]
Example usage:
pyproject.toml[tool.uv.workspace]\nexclude = [\"member1\", \"path/to/member2\", \"libs/*\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#workspace_members","level":4,"title":"members","text":"Packages to include as workspace members.
Supports both globs and explicit paths.
For more information on the glob syntax, refer to the glob documentation.
Default value: []
Type: list[str]
Example usage:
pyproject.toml[tool.uv.workspace]\nmembers = [\"member1\", \"path/to/member2\", \"libs/*\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#configuration","level":2,"title":"Configuration","text":"","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#add-bounds","level":3,"title":"add-bounds","text":"The default version specifier when adding a dependency.
When adding a dependency to the project, if no constraint or URL is provided, a constraint is added based on the latest compatible version of the package. By default, a lower bound constraint is used, e.g., >=1.2.3.
When --frozen is provided, no resolution is performed, and dependencies are always added without constraints.
This option is in preview and may change in any future release.
Default value: \"lower\"
Possible values:
\"lower\": Only a lower bound, e.g., >=1.2.3\"major\": Allow the same major version, similar to the semver caret, e.g., >=1.2.3, <2.0.0\"minor\": Allow the same minor version, similar to the semver tilde, e.g., >=1.2.3, <1.3.0\"exact\": Pin the exact version, e.g., ==1.2.3
Example usage:
pyproject.tomluv.toml [tool.uv]\nadd-bounds = \"major\"\n
add-bounds = \"major\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#allow-insecure-host","level":3,"title":"allow-insecure-host","text":"Allow insecure connections to host.
Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).
WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv]\nallow-insecure-host = [\"localhost:8080\"]\n
allow-insecure-host = [\"localhost:8080\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#cache-dir","level":3,"title":"cache-dir","text":"Path to the cache directory.
Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux and macOS, and %LOCALAPPDATA%\\uv\\cache on Windows.
Default value: None
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv]\ncache-dir = \"./.uv_cache\"\n
cache-dir = \"./.uv_cache\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#cache-keys","level":3,"title":"cache-keys","text":"The keys to consider when caching builds for the project.
Cache keys enable you to specify the files or directories that should trigger a rebuild when modified. By default, uv will rebuild a project whenever the pyproject.toml, setup.py, or setup.cfg files in the project directory are modified, or if a src directory is added or removed, i.e.:
cache-keys = [{ file = \"pyproject.toml\" }, { file = \"setup.py\" }, { file = \"setup.cfg\" }, { dir = \"src\" }]\n
As an example: if a project uses dynamic metadata to read its dependencies from a requirements.txt file, you can specify cache-keys = [{ file = \"requirements.txt\" }, { file = \"pyproject.toml\" }] to ensure that the project is rebuilt whenever the requirements.txt file is modified (in addition to watching the pyproject.toml).
Globs are supported, following the syntax of the glob crate. For example, to invalidate the cache whenever a .toml file in the project directory or any of its subdirectories is modified, you can specify cache-keys = [{ file = \"**/*.toml\" }]. Note that the use of globs can be expensive, as uv may need to walk the filesystem to determine whether any files have changed.
Cache keys can also include version control information. For example, if a project uses setuptools_scm to read its version from a Git commit, you can specify cache-keys = [{ git = { commit = true }, { file = \"pyproject.toml\" }] to include the current Git commit hash in the cache key (in addition to the pyproject.toml). Git tags are also supported via cache-keys = [{ git = { commit = true, tags = true } }].
Cache keys can also include environment variables. For example, if a project relies on MACOSX_DEPLOYMENT_TARGET or other environment variables to determine its behavior, you can specify cache-keys = [{ env = \"MACOSX_DEPLOYMENT_TARGET\" }] to invalidate the cache whenever the environment variable changes.
Cache keys only affect the project defined by the pyproject.toml in which they're specified (as opposed to, e.g., affecting all members in a workspace), and all paths and globs are interpreted as relative to the project directory.
Default value: [{ file = \"pyproject.toml\" }, { file = \"setup.py\" }, { file = \"setup.cfg\" }]
Type: list[dict]
Example usage:
pyproject.tomluv.toml [tool.uv]\ncache-keys = [{ file = \"pyproject.toml\" }, { file = \"requirements.txt\" }, { git = { commit = true } }]\n
cache-keys = [{ file = \"pyproject.toml\" }, { file = \"requirements.txt\" }, { git = { commit = true } }]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#check-url","level":3,"title":"check-url","text":"Check an index URL for existing files to skip duplicate uploads.
This option allows retrying publishing that failed after only some, but not all files have been uploaded, and handles error due to parallel uploads of the same file.
Before uploading, the index is checked. If the exact same file already exists in the index, the file will not be uploaded. If an error occurred during the upload, the index is checked again, to handle cases where the identical file was uploaded twice in parallel.
The exact behavior will vary based on the index. When uploading to PyPI, uploading the same file succeeds even without --check-url, while most other indexes error.
The index must provide one of the supported hashes (SHA-256, SHA-384, or SHA-512).
Default value: None
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv]\ncheck-url = \"https://test.pypi.org/simple\"\n
check-url = \"https://test.pypi.org/simple\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#compile-bytecode","level":3,"title":"compile-bytecode","text":"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.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv]\ncompile-bytecode = true\n
compile-bytecode = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#concurrent-builds","level":3,"title":"concurrent-builds","text":"The maximum number of source distributions that uv will build concurrently at any given time.
Defaults to the number of available CPU cores.
Default value: None
Type: int
Example usage:
pyproject.tomluv.toml [tool.uv]\nconcurrent-builds = 4\n
concurrent-builds = 4\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#concurrent-downloads","level":3,"title":"concurrent-downloads","text":"The maximum number of in-flight concurrent downloads that uv will perform at any given time.
Default value: 50
Type: int
Example usage:
pyproject.tomluv.toml [tool.uv]\nconcurrent-downloads = 4\n
concurrent-downloads = 4\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#concurrent-installs","level":3,"title":"concurrent-installs","text":"The number of threads used when installing and unzipping packages.
Defaults to the number of available CPU cores.
Default value: None
Type: int
Example usage:
pyproject.tomluv.toml [tool.uv]\nconcurrent-installs = 4\n
concurrent-installs = 4\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#config-settings","level":3,"title":"config-settings","text":"Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs.
Default value: {}
Type: dict
Example usage:
pyproject.tomluv.toml [tool.uv]\nconfig-settings = { editable_mode = \"compat\" }\n
config-settings = { editable_mode = \"compat\" }\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#config-settings-package","level":3,"title":"config-settings-package","text":"Settings to pass to the PEP 517 build backend for specific packages, specified as KEY=VALUE pairs.
Accepts a map from package names to string key-value pairs.
Default value: {}
Type: dict
Example usage:
pyproject.tomluv.toml [tool.uv]\nconfig-settings-package = { numpy = { editable_mode = \"compat\" } }\n
config-settings-package = { numpy = { editable_mode = \"compat\" } }\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#dependency-metadata","level":3,"title":"dependency-metadata","text":"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.
Default value: []
Type: list[dict]
Example usage:
pyproject.tomluv.toml [tool.uv]\ndependency-metadata = [\n { name = \"flask\", version = \"1.0.0\", requires-dist = [\"werkzeug\"], requires-python = \">=3.6\" },\n]\n
dependency-metadata = [\n { name = \"flask\", version = \"1.0.0\", requires-dist = [\"werkzeug\"], requires-python = \">=3.6\" },\n]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#exclude-newer","level":3,"title":"exclude-newer","text":"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.
Default value: None
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv]\nexclude-newer = \"2006-12-02T02:07:43Z\"\n
exclude-newer = \"2006-12-02T02:07:43Z\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#exclude-newer-package","level":3,"title":"exclude-newer-package","text":"Limit candidate packages for specific packages to those that were uploaded prior to the given date.
Accepts package-date pairs in a dictionary format.
Default value: None
Type: dict
Example usage:
pyproject.tomluv.toml [tool.uv]\nexclude-newer-package = { tqdm = \"2022-04-04T00:00:00Z\" }\n
exclude-newer-package = { tqdm = \"2022-04-04T00:00:00Z\" }\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#extra-build-dependencies","level":3,"title":"extra-build-dependencies","text":"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.
Default value: []
Type: dict
Example usage:
pyproject.tomluv.toml [tool.uv]\nextra-build-dependencies = { pytest = [\"setuptools\"] }\n
extra-build-dependencies = { pytest = [\"setuptools\"] }\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#extra-build-variables","level":3,"title":"extra-build-variables","text":"Extra environment variables to set when building certain packages.
Environment variables will be added to the environment when building the specified packages.
Default value: {}
Type: dict[str, dict[str, str]]
Example usage:
pyproject.tomluv.toml [tool.uv]\nextra-build-variables = { flash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = \"TRUE\" } }\n
extra-build-variables = { flash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = \"TRUE\" } }\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#extra-index-url","level":3,"title":"extra-index-url","text":"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 or index with default = true. When multiple indexes are provided, earlier values take priority.
To control uv's resolution strategy when multiple indexes are present, see index_strategy.
(Deprecated: use index instead.)
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv]\nextra-index-url = [\"https://download.pytorch.org/whl/cpu\"]\n
extra-index-url = [\"https://download.pytorch.org/whl/cpu\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#find-links","level":3,"title":"find-links","text":"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.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv]\nfind-links = [\"https://download.pytorch.org/whl/torch_stable.html\"]\n
find-links = [\"https://download.pytorch.org/whl/torch_stable.html\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#fork-strategy","level":3,"title":"fork-strategy","text":"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.
Default value: \"requires-python\"
Possible values:
\"fewest\": Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms\"requires-python\": Optimize for selecting latest supported version of each package, for each supported Python version
Example usage:
pyproject.tomluv.toml [tool.uv]\nfork-strategy = \"fewest\"\n
fork-strategy = \"fewest\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#index","level":3,"title":"index","text":"The package indexes to use when resolving dependencies.
Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.
Indexes are considered in the order in which they're defined, such that the first-defined index has the highest priority. Further, the indexes provided by this setting are given higher priority than any indexes specified via index_url or extra_index_url. uv will only consider the first index that contains a given package, unless an alternative index strategy is specified.
If an index is marked as explicit = true, it will be used exclusively for those dependencies that select it explicitly via [tool.uv.sources], as in:
[[tool.uv.index]]\nname = \"pytorch\"\nurl = \"https://download.pytorch.org/whl/cu121\"\nexplicit = true\n\n[tool.uv.sources]\ntorch = { index = \"pytorch\" }\n
If an index is marked as default = true, it will be moved to the end of the prioritized list, such that it is given the lowest priority when resolving packages. Additionally, marking an index as default will disable the PyPI default index.
Default value: \"[]\"
Type: dict
Example usage:
pyproject.tomluv.toml [[tool.uv.index]]\nname = \"pytorch\"\nurl = \"https://download.pytorch.org/whl/cu121\"\n
[[tool.uv.index]]\nname = \"pytorch\"\nurl = \"https://download.pytorch.org/whl/cu121\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#index-strategy","level":3,"title":"index-strategy","text":"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.
Default value: \"first-index\"
Possible values:
\"first-index\": Only use results from the first index that returns a match for a given package name\"unsafe-first-match\": Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next\"unsafe-best-match\": Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
Example usage:
pyproject.tomluv.toml [tool.uv]\nindex-strategy = \"unsafe-best-match\"\n
index-strategy = \"unsafe-best-match\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#index-url","level":3,"title":"index-url","text":"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 or index.
(Deprecated: use index instead.)
Default value: \"https://pypi.org/simple\"
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv]\nindex-url = \"https://test.pypi.org/simple\"\n
index-url = \"https://test.pypi.org/simple\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#keyring-provider","level":3,"title":"keyring-provider","text":"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.
Default value: \"disabled\"
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv]\nkeyring-provider = \"subprocess\"\n
keyring-provider = \"subprocess\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#link-mode","level":3,"title":"link-mode","text":"The method to use when installing packages from the global cache.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
Default value: \"clone\" (macOS) or \"hardlink\" (Linux, Windows)
Possible values:
\"clone\": Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory\"copy\": Copy packages from the wheel into the site-packages directory\"hardlink\": Hard link packages from the wheel into the site-packages directory\"symlink\": Symbolically link packages from the wheel into the site-packages directory
Example usage:
pyproject.tomluv.toml [tool.uv]\nlink-mode = \"copy\"\n
link-mode = \"copy\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#native-tls","level":3,"title":"native-tls","text":"Whether to load TLS certificates from the platform's native certificate store.
By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).
However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv]\nnative-tls = true\n
native-tls = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#no-binary","level":3,"title":"no-binary","text":"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.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv]\nno-binary = true\n
no-binary = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#no-binary-package","level":3,"title":"no-binary-package","text":"Don't install pre-built wheels for a specific package.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv]\nno-binary-package = [\"ruff\"]\n
no-binary-package = [\"ruff\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#no-build","level":3,"title":"no-build","text":"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.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv]\nno-build = true\n
no-build = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#no-build-isolation","level":3,"title":"no-build-isolation","text":"Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv]\nno-build-isolation = true\n
no-build-isolation = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#no-build-isolation-package","level":3,"title":"no-build-isolation-package","text":"Disable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv]\nno-build-isolation-package = [\"package1\", \"package2\"]\n
no-build-isolation-package = [\"package1\", \"package2\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#no-build-package","level":3,"title":"no-build-package","text":"Don't build source distributions for a specific package.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv]\nno-build-package = [\"ruff\"]\n
no-build-package = [\"ruff\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#no-cache","level":3,"title":"no-cache","text":"Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv]\nno-cache = true\n
no-cache = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#no-index","level":3,"title":"no-index","text":"Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv]\nno-index = true\n
no-index = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#no-sources","level":3,"title":"no-sources","text":"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.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv]\nno-sources = true\n
no-sources = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#offline","level":3,"title":"offline","text":"Disable network access, relying only on locally cached data and locally available files.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv]\noffline = true\n
offline = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#prerelease","level":3,"title":"prerelease","text":"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).
Default value: \"if-necessary-or-explicit\"
Possible values:
\"disallow\": Disallow all pre-release versions\"allow\": Allow all pre-release versions\"if-necessary\": Allow pre-release versions if all versions of a package are pre-release\"explicit\": Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements\"if-necessary-or-explicit\": Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
Example usage:
pyproject.tomluv.toml [tool.uv]\nprerelease = \"allow\"\n
prerelease = \"allow\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#preview","level":3,"title":"preview","text":"Whether to enable experimental, preview features.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv]\npreview = true\n
preview = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#publish-url","level":3,"title":"publish-url","text":"The URL for publishing packages to the Python package index (by default: https://upload.pypi.org/legacy/).
Default value: \"https://upload.pypi.org/legacy/\"
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv]\npublish-url = \"https://test.pypi.org/legacy/\"\n
publish-url = \"https://test.pypi.org/legacy/\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pypy-install-mirror","level":3,"title":"pypy-install-mirror","text":"Mirror URL to use for downloading managed PyPy installations.
By default, managed PyPy installations are downloaded from downloads.python.org. This variable can be set to a mirror URL to use a different source for PyPy installations. The provided URL will replace https://downloads.python.org/pypy in, e.g., https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2.
Distributions can be read from a local directory by using the file:// URL scheme.
Default value: None
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv]\npypy-install-mirror = \"https://downloads.python.org/pypy\"\n
pypy-install-mirror = \"https://downloads.python.org/pypy\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#python-downloads","level":3,"title":"python-downloads","text":"Whether to allow Python downloads.
Default value: \"automatic\"
Possible values:
\"automatic\": Automatically download managed Python installations when needed\"manual\": Do not automatically download managed Python installations; require explicit installation\"never\": Do not ever allow Python downloads
Example usage:
pyproject.tomluv.toml [tool.uv]\npython-downloads = \"manual\"\n
python-downloads = \"manual\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#python-downloads-json-url","level":3,"title":"python-downloads-json-url","text":"URL pointing to JSON of custom Python installations.
Note that currently, only local paths are supported.
Default value: None
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv]\npython-downloads-json-url = \"/etc/uv/python-downloads.json\"\n
python-downloads-json-url = \"/etc/uv/python-downloads.json\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#python-install-mirror","level":3,"title":"python-install-mirror","text":"Mirror URL for downloading managed Python installations.
By default, managed Python installations are downloaded from python-build-standalone. This variable can be set to a mirror URL to use a different source for Python installations. The provided URL will replace https://github.com/astral-sh/python-build-standalone/releases/download in, e.g., https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz.
Distributions can be read from a local directory by using the file:// URL scheme.
Default value: None
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv]\npython-install-mirror = \"https://github.com/astral-sh/python-build-standalone/releases/download\"\n
python-install-mirror = \"https://github.com/astral-sh/python-build-standalone/releases/download\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#python-preference","level":3,"title":"python-preference","text":"Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv.
Default value: \"managed\"
Possible values:
\"only-managed\": Only use managed Python installations; never use system Python installations\"managed\": Prefer managed Python installations over system Python installations\"system\": Prefer system Python installations over managed Python installations\"only-system\": Only use system Python installations; never use managed Python installations
Example usage:
pyproject.tomluv.toml [tool.uv]\npython-preference = \"managed\"\n
python-preference = \"managed\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#reinstall","level":3,"title":"reinstall","text":"Reinstall all packages, regardless of whether they're already installed. Implies refresh.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv]\nreinstall = true\n
reinstall = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#reinstall-package","level":3,"title":"reinstall-package","text":"Reinstall a specific package, regardless of whether it's already installed. Implies refresh-package.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv]\nreinstall-package = [\"ruff\"]\n
reinstall-package = [\"ruff\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#required-version","level":3,"title":"required-version","text":"Enforce a requirement on the version of uv.
If the version of uv does not meet the requirement at runtime, uv will exit with an error.
Accepts a PEP 440 specifier, like ==0.5.0 or >=0.5.0.
Default value: null
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv]\nrequired-version = \">=0.5.0\"\n
required-version = \">=0.5.0\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#resolution","level":3,"title":"resolution","text":"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).
Default value: \"highest\"
Possible values:
\"highest\": Resolve the highest compatible version of each package\"lowest\": Resolve the lowest compatible version of each package\"lowest-direct\": Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
Example usage:
pyproject.tomluv.toml [tool.uv]\nresolution = \"lowest-direct\"\n
resolution = \"lowest-direct\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#trusted-publishing","level":3,"title":"trusted-publishing","text":"Configure trusted publishing.
By default, uv checks for trusted publishing when running in a supported environment, but ignores it if it isn't configured.
uv's supported environments for trusted publishing include GitHub Actions and GitLab CI/CD.
Default value: automatic
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv]\ntrusted-publishing = \"always\"\n
trusted-publishing = \"always\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#upgrade","level":3,"title":"upgrade","text":"Allow package upgrades, ignoring pinned versions in any existing output file.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv]\nupgrade = true\n
upgrade = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#upgrade-package","level":3,"title":"upgrade-package","text":"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).
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv]\nupgrade-package = [\"ruff\"]\n
upgrade-package = [\"ruff\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip","level":3,"title":"pip","text":"Settings that are specific to the uv pip command-line interface.
These values will be ignored when running commands outside the uv pip namespace (e.g., uv lock, uvx).
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_all-extras","level":4,"title":"all-extras","text":"Include all optional dependencies.
Only applies to pyproject.toml, setup.py, and setup.cfg sources.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nall-extras = true\n
[pip]\nall-extras = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_allow-empty-requirements","level":4,"title":"allow-empty-requirements","text":"Allow uv pip sync with empty requirements, which will clear the environment of all packages.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nallow-empty-requirements = true\n
[pip]\nallow-empty-requirements = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_annotation-style","level":4,"title":"annotation-style","text":"The style of the annotation comments included in the output file, used to indicate the source of each package.
Default value: \"split\"
Possible values:
\"line\": Render the annotations on a single, comma-separated line\"split\": Render each annotation on its own line
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nannotation-style = \"line\"\n
[pip]\nannotation-style = \"line\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_break-system-packages","level":4,"title":"break-system-packages","text":"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).
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nbreak-system-packages = true\n
[pip]\nbreak-system-packages = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_compile-bytecode","level":4,"title":"compile-bytecode","text":"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.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\ncompile-bytecode = true\n
[pip]\ncompile-bytecode = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_config-settings","level":4,"title":"config-settings","text":"Settings to pass to the PEP 517 build backend, specified as KEY=VALUE pairs.
Default value: {}
Type: dict
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nconfig-settings = { editable_mode = \"compat\" }\n
[pip]\nconfig-settings = { editable_mode = \"compat\" }\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_config-settings-package","level":4,"title":"config-settings-package","text":"Settings to pass to the PEP 517 build backend for specific packages, specified as KEY=VALUE pairs.
Default value: {}
Type: dict
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nconfig-settings-package = { numpy = { editable_mode = \"compat\" } }\n
[pip]\nconfig-settings-package = { numpy = { editable_mode = \"compat\" } }\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_custom-compile-command","level":4,"title":"custom-compile-command","text":"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.
Default value: None
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\ncustom-compile-command = \"./custom-uv-compile.sh\"\n
[pip]\ncustom-compile-command = \"./custom-uv-compile.sh\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_dependency-metadata","level":4,"title":"dependency-metadata","text":"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.
Default value: []
Type: list[dict]
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\ndependency-metadata = [\n { name = \"flask\", version = \"1.0.0\", requires-dist = [\"werkzeug\"], requires-python = \">=3.6\" },\n]\n
[pip]\ndependency-metadata = [\n { name = \"flask\", version = \"1.0.0\", requires-dist = [\"werkzeug\"], requires-python = \">=3.6\" },\n]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_emit-build-options","level":4,"title":"emit-build-options","text":"Include --no-binary and --only-binary entries in the output file generated by uv pip compile.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nemit-build-options = true\n
[pip]\nemit-build-options = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_emit-find-links","level":4,"title":"emit-find-links","text":"Include --find-links entries in the output file generated by uv pip compile.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nemit-find-links = true\n
[pip]\nemit-find-links = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_emit-index-annotation","level":4,"title":"emit-index-annotation","text":"Include comment annotations indicating the index used to resolve each package (e.g., # from https://pypi.org/simple).
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nemit-index-annotation = true\n
[pip]\nemit-index-annotation = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_emit-index-url","level":4,"title":"emit-index-url","text":"Include --index-url and --extra-index-url entries in the output file generated by uv pip compile.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nemit-index-url = true\n
[pip]\nemit-index-url = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_emit-marker-expression","level":4,"title":"emit-marker-expression","text":"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.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nemit-marker-expression = true\n
[pip]\nemit-marker-expression = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_exclude-newer","level":4,"title":"exclude-newer","text":"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.
Default value: None
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nexclude-newer = \"2006-12-02T02:07:43Z\"\n
[pip]\nexclude-newer = \"2006-12-02T02:07:43Z\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_exclude-newer-package","level":4,"title":"exclude-newer-package","text":"Limit candidate packages for specific packages to those that were uploaded prior to the given date.
Accepts package-date pairs in a dictionary format.
Default value: None
Type: dict
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nexclude-newer-package = { tqdm = \"2022-04-04T00:00:00Z\" }\n
[pip]\nexclude-newer-package = { tqdm = \"2022-04-04T00:00:00Z\" }\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_extra","level":4,"title":"extra","text":"Include optional dependencies from the specified extra; may be provided more than once.
Only applies to pyproject.toml, setup.py, and setup.cfg sources.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nextra = [\"dev\", \"docs\"]\n
[pip]\nextra = [\"dev\", \"docs\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_extra-build-dependencies","level":4,"title":"extra-build-dependencies","text":"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.
Default value: []
Type: dict
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nextra-build-dependencies = { pytest = [\"setuptools\"] }\n
[pip]\nextra-build-dependencies = { pytest = [\"setuptools\"] }\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_extra-build-variables","level":4,"title":"extra-build-variables","text":"Extra environment variables to set when building certain packages.
Environment variables will be added to the environment when building the specified packages.
Default value: {}
Type: dict[str, dict[str, str]]
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nextra-build-variables = { flash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = \"TRUE\" } }\n
[pip]\nextra-build-variables = { flash-attn = { FLASH_ATTENTION_SKIP_CUDA_BUILD = \"TRUE\" } }\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_extra-index-url","level":4,"title":"extra-index-url","text":"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.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nextra-index-url = [\"https://download.pytorch.org/whl/cpu\"]\n
[pip]\nextra-index-url = [\"https://download.pytorch.org/whl/cpu\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_find-links","level":4,"title":"find-links","text":"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.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nfind-links = [\"https://download.pytorch.org/whl/torch_stable.html\"]\n
[pip]\nfind-links = [\"https://download.pytorch.org/whl/torch_stable.html\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_fork-strategy","level":4,"title":"fork-strategy","text":"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.
Default value: \"requires-python\"
Possible values:
\"fewest\": Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms\"requires-python\": Optimize for selecting latest supported version of each package, for each supported Python version
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nfork-strategy = \"fewest\"\n
[pip]\nfork-strategy = \"fewest\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_generate-hashes","level":4,"title":"generate-hashes","text":"Include distribution hashes in the output file.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\ngenerate-hashes = true\n
[pip]\ngenerate-hashes = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_group","level":4,"title":"group","text":"Include the following dependency groups.
Default value: None
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\ngroup = [\"dev\", \"docs\"]\n
[pip]\ngroup = [\"dev\", \"docs\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_index-strategy","level":4,"title":"index-strategy","text":"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.
Default value: \"first-index\"
Possible values:
\"first-index\": Only use results from the first index that returns a match for a given package name\"unsafe-first-match\": Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next\"unsafe-best-match\": Search for every package name across all indexes, preferring the \"best\" version found. If a package version is in multiple indexes, only look at the entry for the first index
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nindex-strategy = \"unsafe-best-match\"\n
[pip]\nindex-strategy = \"unsafe-best-match\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_index-url","level":4,"title":"index-url","text":"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.
Default value: \"https://pypi.org/simple\"
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nindex-url = \"https://test.pypi.org/simple\"\n
[pip]\nindex-url = \"https://test.pypi.org/simple\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_keyring-provider","level":4,"title":"keyring-provider","text":"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.
Default value: disabled
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nkeyring-provider = \"subprocess\"\n
[pip]\nkeyring-provider = \"subprocess\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_link-mode","level":4,"title":"link-mode","text":"The method to use when installing packages from the global cache.
Defaults to clone (also known as Copy-on-Write) on macOS, and hardlink on Linux and 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.
Default value: \"clone\" (macOS) or \"hardlink\" (Linux, Windows)
Possible values:
\"clone\": Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory\"copy\": Copy packages from the wheel into the site-packages directory\"hardlink\": Hard link packages from the wheel into the site-packages directory\"symlink\": Symbolically link packages from the wheel into the site-packages directory
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nlink-mode = \"copy\"\n
[pip]\nlink-mode = \"copy\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_no-annotate","level":4,"title":"no-annotate","text":"Exclude comment annotations indicating the source of each package from the output file generated by uv pip compile.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nno-annotate = true\n
[pip]\nno-annotate = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_no-binary","level":4,"title":"no-binary","text":"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:.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nno-binary = [\"ruff\"]\n
[pip]\nno-binary = [\"ruff\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_no-build","level":4,"title":"no-build","text":"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:.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nno-build = true\n
[pip]\nno-build = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_no-build-isolation","level":4,"title":"no-build-isolation","text":"Disable isolation when building source distributions.
Assumes that build dependencies specified by PEP 518 are already installed.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nno-build-isolation = true\n
[pip]\nno-build-isolation = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_no-build-isolation-package","level":4,"title":"no-build-isolation-package","text":"Disable isolation when building source distributions for a specific package.
Assumes that the packages' build dependencies specified by PEP 518 are already installed.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nno-build-isolation-package = [\"package1\", \"package2\"]\n
[pip]\nno-build-isolation-package = [\"package1\", \"package2\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_no-deps","level":4,"title":"no-deps","text":"Ignore package dependencies, instead only add those packages explicitly listed on the command line to the resulting requirements file.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nno-deps = true\n
[pip]\nno-deps = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_no-emit-package","level":4,"title":"no-emit-package","text":"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.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nno-emit-package = [\"ruff\"]\n
[pip]\nno-emit-package = [\"ruff\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_no-extra","level":4,"title":"no-extra","text":"Exclude the specified optional dependencies if all-extras is supplied.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nall-extras = true\nno-extra = [\"dev\", \"docs\"]\n
[pip]\nall-extras = true\nno-extra = [\"dev\", \"docs\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_no-header","level":4,"title":"no-header","text":"Exclude the comment header at the top of output file generated by uv pip compile.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nno-header = true\n
[pip]\nno-header = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_no-index","level":4,"title":"no-index","text":"Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and those provided via --find-links.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nno-index = true\n
[pip]\nno-index = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_no-sources","level":4,"title":"no-sources","text":"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.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nno-sources = true\n
[pip]\nno-sources = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_no-strip-extras","level":4,"title":"no-strip-extras","text":"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.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nno-strip-extras = true\n
[pip]\nno-strip-extras = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_no-strip-markers","level":4,"title":"no-strip-markers","text":"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.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nno-strip-markers = true\n
[pip]\nno-strip-markers = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_only-binary","level":4,"title":"only-binary","text":"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:.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nonly-binary = [\"ruff\"]\n
[pip]\nonly-binary = [\"ruff\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_output-file","level":4,"title":"output-file","text":"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.
Default value: None
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\noutput-file = \"requirements.txt\"\n
[pip]\noutput-file = \"requirements.txt\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_prefix","level":4,"title":"prefix","text":"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.
Default value: None
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nprefix = \"./prefix\"\n
[pip]\nprefix = \"./prefix\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_prerelease","level":4,"title":"prerelease","text":"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).
Default value: \"if-necessary-or-explicit\"
Possible values:
\"disallow\": Disallow all pre-release versions\"allow\": Allow all pre-release versions\"if-necessary\": Allow pre-release versions if all versions of a package are pre-release\"explicit\": Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements\"if-necessary-or-explicit\": Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nprerelease = \"allow\"\n
[pip]\nprerelease = \"allow\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_python","level":4,"title":"python","text":"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.
Default value: None
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\npython = \"3.10\"\n
[pip]\npython = \"3.10\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_python-platform","level":4,"title":"python-platform","text":"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.
Default value: None
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\npython-platform = \"x86_64-unknown-linux-gnu\"\n
[pip]\npython-platform = \"x86_64-unknown-linux-gnu\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_python-version","level":4,"title":"python-version","text":"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.
Default value: None
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\npython-version = \"3.8\"\n
[pip]\npython-version = \"3.8\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_reinstall","level":4,"title":"reinstall","text":"Reinstall all packages, regardless of whether they're already installed. Implies refresh.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nreinstall = true\n
[pip]\nreinstall = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_reinstall-package","level":4,"title":"reinstall-package","text":"Reinstall a specific package, regardless of whether it's already installed. Implies refresh-package.
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nreinstall-package = [\"ruff\"]\n
[pip]\nreinstall-package = [\"ruff\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_require-hashes","level":4,"title":"require-hashes","text":"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.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nrequire-hashes = true\n
[pip]\nrequire-hashes = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_resolution","level":4,"title":"resolution","text":"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).
Default value: \"highest\"
Possible values:
\"highest\": Resolve the highest compatible version of each package\"lowest\": Resolve the lowest compatible version of each package\"lowest-direct\": Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nresolution = \"lowest-direct\"\n
[pip]\nresolution = \"lowest-direct\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_strict","level":4,"title":"strict","text":"Validate the Python environment, to detect packages with missing dependencies and other issues.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nstrict = true\n
[pip]\nstrict = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_system","level":4,"title":"system","text":"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.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nsystem = true\n
[pip]\nsystem = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_target","level":4,"title":"target","text":"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.
Default value: None
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\ntarget = \"./target\"\n
[pip]\ntarget = \"./target\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_torch-backend","level":4,"title":"torch-backend","text":"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 option is in preview and may change in any future release.
Default value: null
Type: str
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\ntorch-backend = \"auto\"\n
[pip]\ntorch-backend = \"auto\"\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_universal","level":4,"title":"universal","text":"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.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nuniversal = true\n
[pip]\nuniversal = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_upgrade","level":4,"title":"upgrade","text":"Allow package upgrades, ignoring pinned versions in any existing output file.
Default value: false
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nupgrade = true\n
[pip]\nupgrade = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_upgrade-package","level":4,"title":"upgrade-package","text":"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).
Default value: []
Type: list[str]
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nupgrade-package = [\"ruff\"]\n
[pip]\nupgrade-package = [\"ruff\"]\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/settings/#pip_verify-hashes","level":4,"title":"verify-hashes","text":"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.
Default value: true
Type: bool
Example usage:
pyproject.tomluv.toml [tool.uv.pip]\nverify-hashes = true\n
[pip]\nverify-hashes = true\n
","path":["Reference","Settings"],"tags":[]},{"location":"reference/internals/","level":1,"title":"Internals","text":"The internals section provides details about uv's internal components and implementation details.
- Resolver
","path":["Reference","Internals"],"tags":[]},{"location":"reference/internals/resolver/","level":1,"title":"Resolver internals","text":"Tip
This document focuses on the internal workings of uv's resolver. For using uv, see the resolution concept documentation.
","path":["Reference","Internals","Resolver internals"],"tags":[]},{"location":"reference/internals/resolver/#resolver","level":2,"title":"Resolver","text":"As defined in a textbook, resolution, or finding a set of version to install from a given set of requirements, is equivalent to the SAT problem and thereby NP-complete: in the worst case you have to try all possible combinations of all versions of all packages and there are no general, fast algorithms. In practice, this is misleading for a number of reasons:
- The slowest part of resolution in uv is loading package and version metadata, even if it's cached.
- There are many possible solutions, but some are preferable to others. For example, we generally prefer using the latest version of packages.
- Package dependencies are complex, e.g., there are contiguous versions ranges — not arbitrary boolean inclusion/exclusions of versions, adjacent releases often have the same or similar requirements, etc.
- For most resolutions, the resolver doesn't need to backtrack, picking versions iteratively is sufficient. If there are version preferences from a previous resolution, barely any work needs to be done.
- When resolution fails, more information is needed than a message that there is no solution (as is seen in SAT solvers). Instead, the resolver should produce an understandable error trace that states which packages are involved in away to allows a user to remove the conflict.
- The most important heuristic for performance and user experience is determining the order in which decisions are made through prioritization.
uv uses pubgrub-rs, the Rust implementation of PubGrub, an incremental version solver. PubGrub in uv works in the following steps:
- Start with a partial solution that declares which packages versions have been selected and which are undecided. Initially, only a virtual root package is decided.
- The highest priority package is selected from the undecided packages. Roughly, packages with URLs (including file, git, etc.) have the highest priority, then those with more exact specifiers (such as
==), then those with less strict specifiers. Inside each category, packages are ordered by when they were first seen (i.e. order in a file), making the resolution deterministic. - A version is picked for the selected package. The version must works with all specifiers from the requirements in the partial solution and must not be previously marked as incompatible. The resolver prefers versions from a lockfile (
uv.lock or -o requirements.txt) and those installed in the current environment. Versions are checked from highest to lowest (unless using an alternative resolution strategy). - All requirements of the selected package version are added to the undecided packages. uv prefetches their metadata in the background to improve performance.
- The process is either repeated with the next package unless a conflict is detected, in which the resolver will backtrack. For example, the partial solution contains, among other packages,
a 2 then b 2 with the requirements a 2 -> c 1 and b 2 -> c 2. No compatible version of c can be found. PubGrub can determine this was caused by a 2 and b 2 and add the incompatibility {a 2, b 2}, meaning that when either is picked, the other cannot be selected. The partial solution is restored to a 2 with the tracked incompatibility and the resolver attempts to pick a new version for b.
Eventually, the resolver either picks compatible versions for all packages (a successful resolution) or there is an incompatibility including the virtual \"root\" package which defines the versions requested by the user. An incompatibility with the root package indicates that whatever versions of the root dependencies and their transitive dependencies are picked, there will always be a conflict. From the incompatibilities tracked in PubGrub, an error message is constructed to enumerate the involved packages.
Tip
For more details on the PubGrub algorithm, see Internals of the PubGrub algorithm.
In addition to PubGrub's base algorithm, we also use a heuristic that backtracks and switches the order of two packages if they have been conflicting too much.
","path":["Reference","Internals","Resolver internals"],"tags":[]},{"location":"reference/internals/resolver/#forking","level":2,"title":"Forking","text":"Python resolvers historically didn't support backtracking, and even with backtracking, resolution was usually limited to single environment, which one specific architecture, operating system, Python version, and Python implementation. Some packages use contradictory requirements for different environments, for example:
numpy>=2,<3 ; python_version >= \"3.11\"\nnumpy>=1.16,<2 ; python_version < \"3.11\"\n
Since Python only allows one version of each package, a naive resolver would error here. Inspired by Poetry, uv uses a forking resolver: whenever there are multiple requirements for a package with different markers, the resolution is split.
In the above example, the partial solution would be split into two resolutions, one for python_version >= \"3.11\" and one for python_version < \"3.11\".
If markers overlap or are missing a part of the marker space, the resolver splits additional times — there can be many forks per package. For example, given:
flask > 1 ; sys_platform == 'darwin'\nflask > 2 ; sys_platform == 'win32'\nflask\n
A fork would be created for sys_platform == 'darwin', for sys_platform == 'win32', and for sys_platform != 'darwin' and sys_platform != 'win32'.
Forks can be nested, e.g., each fork is dependent on any previous forks that occurred. Forks with identical packages are merged to keep the number of forks low.
Tip
Forking can be observed in the logs of uv lock -v by looking for Splitting resolution on ..., Solving split ... (requires-python: ...) and Split ... resolution took ....
One difficulty in a forking resolver is that where splits occur is dependent on the order packages are seen, which is in turn dependent on the preferences, e.g., from uv.lock. So it is possible for the resolver to solve the requirements with specific forks, write this to the lockfile, and when the resolver is invoked again, a different solution is found because the preferences result in different fork points. To avoid this, the resolution-markers of each fork and each package that diverges between forks is written to the lockfile. When performing a new resolution, the forks from the lockfile are used to ensure the resolution is stable. When requirements change, new forks may be added to the saved forks.
","path":["Reference","Internals","Resolver internals"],"tags":[]},{"location":"reference/internals/resolver/#wheel-tags","level":2,"title":"Wheel tags","text":"While uv's resolution is universal with respect to environment markers, this doesn't extend to wheel tags. Wheel tags can encode the Python version, Python implementation, operating system, and architecture. For example, torch-2.4.0-cp312-cp312-manylinux2014_aarch64.whl is only compatible with CPython 3.12 on arm64 Linux with glibc>=2.17 (per the manylinux2014 policy), while tqdm-4.66.4-py3-none-any.whl works with all Python 3 versions and interpreters on any operating system and architecture. Most projects have a universally compatible source distribution that can be used when attempted to install a package that has no compatible wheel, but some packages, such as torch, don't publish a source distribution. In this case an installation on, e.g., Python 3.13, an uncommon operating system, or architecture, will fail and complain that there is no matching wheel.
","path":["Reference","Internals","Resolver internals"],"tags":[]},{"location":"reference/internals/resolver/#marker-and-wheel-tag-filtering","level":2,"title":"Marker and wheel tag filtering","text":"In every fork, we know what markers are possible. In non-universal resolution, we know their exact values. In universal mode, we know at least a constraint for the python requirement, e.g., requires-python = \">=3.12\" means that importlib_metadata; python_version < \"3.10\" can be discarded because it can never be installed. If additionally tool.uv.environments is set, we can filter out requirements with markers disjoint with those environments. Inside each fork, we can additionally filter by the fork markers.
There is some redundancy in the marker expressions, where the value of one marker field implies the value of another field. Internally, we normalize python_version and python_full_version as well as known values of platform_system and sys_platform to a shared canonical representation, so they can match against each other.
When we selected a version with a local tag (e.g.,1.2.3+localtag) and the wheels don't cover support for Windows, Linux and macOS, and there is a base version without tag (e.g.,1.2.3) with support for a missing platform, we fork trying to extend the platform support by using both the version with local tag and without local tag depending on the platform. This helps with packages that use the local tag for different hardware accelerators such as torch. While there is no 1:1 mapping between wheel tags and markers, we can do a mapping for well-known platforms, including Windows, Linux and macOS.
","path":["Reference","Internals","Resolver internals"],"tags":[]},{"location":"reference/internals/resolver/#metadata-consistency","level":2,"title":"Metadata consistency","text":"uv, similar to poetry, requires that wheels of a single version of a package in a specific index have the same dependencies (Requires-Dist in METADATA), including wheels build from a source distribution. More generally, uv assumes that each wheel has the same METADATA file in its dist-info directory.
numpy 2.3.2 for example has 73 wheels. Without this assumption, uv would have to make 73 network requests to fetch its metadata, instead of a single one. Another problem we would have without metadata consistency is the lack of a 1:1 mapping between markers and wheel tags. Wheel tags can include the glibc version while the PEP 508 markers cannot represent it. If wheels had different metadata, a universal resolver would have to track two dimensions simultaneously, PEP 508 markers and wheel tags. This would increase complexity a lot, and the correspondence between the two is not properly specified. PEP 508 markers have been introduced specifically to allow different dependencies between different platform, i.e. to have a single dependency declaration for all wheels, such as project.[optional-]dependencies. If the markers are not sufficient, we should extend PEP 508 markers instead of using a parallel system of wheel tags.
Another aspect of metadata consistency is that a source distribution must build into a wheel with the same metadata as the wheels, or if there are no wheels, into the same metadata each time. If this assumption is violated, sound dependency locking becomes impossible: Consider a package A has a source distribution. During resolution, we build A v1 and obtain the dependencies B>=2,<3. We lock A==1 and B==2. When installing the lockfile on the target machine, we build again and obtain dependencies B>=3,<4 and C>=1,<2. The lockfile fails to install: Due to the changed constraints, the locked version of B is incompatible, and there's no locked candidate for C. Re-resolving after this would both be a reproducibility problem (the lockfile is effectively ignored) and a security concern (C has not been reviewed, neither was B==3). It's possible to fail on installation if that happens, but a late error, possibly during deployment, is a bad user experience. There is already a case where uv fails on installation, packages with no source distribution and only platform specific wheels incompatible with the current platform. While uv has required environments as mitigation, this requires a not well known configuration option, and questions around (un)supported environments are one of the most common problem for uv users. A similar situation with source distributions should be avoided.
While older versions of torch and tensorflow had inconsistent metadata, all recent versions have consistent metadata, and we are not aware of any major package with inconsistent metadata. There is however no requirement in the Python packaging standards that metadata must be consistent, and requests to enforce this in the standards have been rejected (https://discuss.python.org/t/enforcing-consistent-metadata-for-packages/50008).
There are packages that have native code that links against the native code in another package, such as torch. These package may support building against a range of torch versions, but once built, they are constrained to a specific torch version, and the runtime torch version must match the build-time version. These are currently a pain point across all package managers, as all major package managers from pip to uv cache source distribution builds. uv supports multiple builds depending on the version of the already installed package using tool.uv.extra-build-dependencies with match-runtime = true. This is a workaround that needs to be made on the user side for each affected package, instead of library developers declaring this requirement, which would be possible with native standards support.
","path":["Reference","Internals","Resolver internals"],"tags":[]},{"location":"reference/internals/resolver/#requires-python","level":2,"title":"Requires-python","text":"To ensure that a resolution with requires-python = \">=3.9\" can actually be installed for the included Python versions, uv requires that all dependencies have the same minimum Python version. Package versions that declare a higher minimum Python version, e.g., requires-python = \">=3.10\", are rejected, because a resolution with that version can't be installed on Python 3.9. This ensures that when you are on an old Python version, you can install old packages, instead of getting newer packages that require newer Python syntax or standard library features.
uv ignores upper-bounds on requires-python, with special handling for packages with only ABI-specific wheels. For example, if a package declares requires-python = \">=3.8,<4\", the <4 part is ignored. There is a detailed discussion with drawbacks and alternatives in #4022 and this DPO thread, this section summarizes the aspects most relevant to uv's design.
For most projects, it's not possible to determine whether they will be compatible with a new version before it's released, so blocking newer versions in advance would block users from upgrading or testing newer Python versions. The exceptions are packages which use the unstable C ABI or internals of CPython such as its bytecode format.
Introducing a requires-python upper bound to a project that previously wasn't using one will not prevent the project from being used on a too recent Python version. Instead of failing, the resolver will pick an older version without the bound, circumventing the bound.
For the resolution to be as universally installable as possible, uv ensures that the selected dependency versions are compatible with the requires-python range of the project. For example, for a project with requires-python = \">=3.12\", uv will not use a dependency version with requires-python = \">=3.13\", as otherwise the resolution is not installable on Python 3.12, which the project declares to support. Applying the same logic to upper bounds means that bumping the upper Python version bound on a project makes it compatible with less dependency versions, potentially failing to resolve when no version of a dependency supports the required range. (Bumping the lower Python version bound has the inverse effect, it only increases the set of supported dependency versions.)
Note that this is different for Conda, as the Conda solver also determines the Python version, so it can choose a lower Python version instead. Conda can also change metadata after a release, so it can update compatibility for a new Python version, while metadata on PyPI cannot be changed once published.
Ignoring an upper bound is a problem for packages such as numpy which use the version-dependent C API of CPython. As of writing, each numpy release support 4 Python minor versions, e.g., numpy 2.0.0 has wheels for CPython 3.9 through 3.12 and declares requires-python = \">=3.9\", while numpy 2.1.0 has wheels for CPython 3.10 through 3.13 and declares requires-python = \">=3.10\". This means that when uv resolves a numpy>=2,<3 requirement in a project with requires-python = \">=3.9\", it selects numpy 2.0.0 and the lockfile doesn't install on Python 3.13 or newer. To alleviate this, whenever uv rejects a version that requires a newer Python version, we fork by splitting the resolution markers on that Python version. This behavior can be controlled by --fork-strategy. In the example case, upon encountering numpy 2.1.0 we fork into Python versions >=3.9,<3.10 and >=3.10 and resolve two different numpy versions:
numpy==2.0.0; python_version >= \"3.9\" and python_version < \"3.10\"\nnumpy==2.1.0; python_version >= \"3.10\"\n
There's one case where uv does consider the upper bound: When the project uses an upper bound on requires Python, such as requires-python = \"==3.13.*\" for an application that only deploys to Python 3.13. uv prunes wheels from the lockfile that are outside the range (e.g., cp312 and cp314) in a post-processing step, which does not influence the resolution itself.
","path":["Reference","Internals","Resolver internals"],"tags":[]},{"location":"reference/internals/resolver/#url-dependencies","level":2,"title":"URL dependencies","text":"In uv, a dependency can either be a registry dependency, a package with a version specifier or the plain package name, or a URL dependency. All requirements in the form {name} @ {url} are URL dependencies, and also all dependencies that have a git,url, path, or workspace source.
When a URL is declared for a package, uv pins the package to this URL, and the version this URL implies. If there are two conflicting URLs for a package, the resolver errors, as a URL can only be declared as something akin to an exact == pin, and not as list of URLs. A list of URLs is supported through flat indexes instead.
uv requires that URLs are either declared directly (in the project, in a workspace member, in a constraint, or in an override, any location that is discovered directly), or by other URL dependencies. uv discovers all URL dependencies and their transitive URL dependencies ahead of the resolution and pins all packages to the URLs and the versions they imply.
uv does not allow URLs in index packages. This has two reasons: One is a security and predictability aspect, that forbids registry distributions to point to non-registry distributions and helps auditing which URLs can be accessed. For example, when only using one index URL and no URL dependencies, uv will not install any package from outside the index.
The other is that URLs can add additional versions to the resolution. Say the root package depends on foo, bar, and baz, all registry dependencies. foo depends on bar >= 2, but bar only has version 1 on the index. With the incremental approach, this is an error: foo cannot be fulfilled, there is a resolver error. If URLs on index packages were allowed, it could be that there is a version of baz declares a dependency on baz-core and that has a version that declares bar @ https://example.com/bar-2-py3-none-any.whl adding a version of bar that makes requirements resolve. If a dependency can add new versions, discarding any version in the resolver would require looking at all possible versions of all direct and transitive dependencies. This breaks the core assumption incremental resolvers make that the set of versions for a package is static and would require to always fetch the metadata for all possibly reachable version.
","path":["Reference","Internals","Resolver internals"],"tags":[]},{"location":"reference/internals/resolver/#prioritization","level":2,"title":"Prioritization","text":"Prioritization is important for both performance and for better resolutions.
If we try many versions we have to later discard, resolution is slow, both because we have to read metadata we didn't need and because we have to track a lot of (conflict) information for this discarded subtree.
There are expectations about which solution uv should choose, even if the version constraints allow multiple solutions. Generally, a desirable solution prioritizes use the highest versions for direct dependencies over those for indirect dependencies, it avoids backtracking to very old versions and can be installed on a target machine.
Internally, uv represent each package with a given package name as a number of virtual packages, for example, one package for each activated extra, for dependency groups, or for having a marker. While PubGrub needs to choose a version for each virtual package, uv's prioritization works on the package name level.
Whenever we encounter a requirement on a package, we match it to a priority. The root package and URL requirements have the highest priority, then singleton requirements with the == operator, as their version can be directly determined, then highly conflicting packages (next paragraph), and finally all other packages. Inside each category, packages are sorted by when they were first encountered, creating a breadth first search that prioritizes direct dependencies including workspace dependencies over transitive dependencies.
A common problem is that we have a package A with a higher priority than package B, and B is only compatible with older versions of A. We decide the latest version for package A. Each time we decide a version for B, it is immediately discarded due to the conflict with A. We have to try all possible versions of B, until we have either exhausted the possible range (slow), pick a very old version that doesn't depend on A, but most likely isn't compatible with the project either (bad) or fail to build a very old version (bad). Once we see such conflict happen five time, we set A and B to special highly-conflicting priority levels, and set them so that B is decided before A. We then manually backtrack to a state before deciding A, in the next iteration now deciding B instead of A. See #8157 and #9843 for a more detailed description with real world examples.
","path":["Reference","Internals","Resolver internals"],"tags":[]},{"location":"reference/policies/","level":1,"title":"Policies","text":" - Versioning
- Platform support
- License
","path":["Reference","Policies"],"tags":[]},{"location":"reference/policies/license/","level":1,"title":"License","text":"uv is licensed under either of
- Apache License, Version 2.0
LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0
- MIT License
LICENSE-MIT or https://opensource.org/licenses/MIT
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in uv by you, as defined in the Apache-2.0 license, shall be dually licensed as above, without any additional terms or conditions.
","path":["Reference","Policies","License"],"tags":[]},{"location":"reference/policies/platforms/","level":1,"title":"Platform support","text":"uv has Tier 1 support for the following platforms:
- macOS (Apple Silicon)
- macOS (x86_64)
- Linux (x86_64)
- Windows (x86_64)
uv is continuously built, tested, and developed against its Tier 1 platforms. Inspired by the Rust project, Tier 1 can be thought of as \"guaranteed to work\".
uv has Tier 2 support (\"guaranteed to build\") for the following platforms:
- Linux (PPC64)
- Linux (PPC64LE)
- Linux (RISC-V64)
- Linux (aarch64)
- Linux (armv7)
- Linux (i686)
- Linux (s390x)
- Windows (arm64)
uv ships pre-built wheels to PyPI for its Tier 1 and Tier 2 platforms. However, while Tier 2 platforms are continuously built, they are not continuously tested or developed against, and so stability may vary in practice.
Beyond the Tier 1 and Tier 2 platforms, uv is known to build on i686 Windows, and known not to build on aarch64 Windows, but does not consider either platform to be supported at this time. The minimum supported Windows versions are Windows 10 and Windows Server 2016, following Rust's own Tier 1 support.
","path":["Reference","Policies","Platform support"],"tags":[]},{"location":"reference/policies/platforms/#macos-versions","level":2,"title":"macOS versions","text":"uv supports macOS 13+ (Ventura).
uv is known to work on macOS 12, but requires installation of a realpath executable.
","path":["Reference","Policies","Platform support"],"tags":[]},{"location":"reference/policies/platforms/#python-support","level":2,"title":"Python support","text":"uv supports and is tested against the following Python versions:
- 3.8
- 3.9
- 3.10
- 3.11
- 3.12
- 3.13
- 3.14
uv has Tier 1 support for the following Python implementations:
- CPython
As with platforms, Tier 1 support can be thought of \"guaranteed to work\". uv supports managed installations of these implementations, and the builds are maintained by Astral.
uv has Tier 2 support for:
- PyPy
- GraalPy
uv is \"expected to work\" with these implementations. uv also supports managed installations of these Python implementations, but the builds are not maintained by Astral.
uv has Tier 3 support for:
- Pyston
- Pyodide
uv \"should work\" with these implementations, but stability may vary.
","path":["Reference","Policies","Platform support"],"tags":[]},{"location":"reference/policies/versioning/","level":1,"title":"Versioning","text":"uv uses a custom versioning scheme in which the minor version number is bumped for breaking changes, and the patch version number is bumped for bug fixes, enhancements, and other non-breaking changes.
uv is widely used in production. However, we value the ability to iterate on new features quickly and gather changes that could be breaking into clearly marked releases.
Once uv v1.0.0 is released, the versioning scheme will adhere to Semantic Versioning. There is not a particular goal that must be achieved for uv to reach this milestone.
uv's changelog can be viewed on GitHub.
","path":["Reference","Policies","Versioning"],"tags":[]},{"location":"reference/policies/versioning/#cache-versioning","level":2,"title":"Cache versioning","text":"Cache versions are considered internal to uv, and so may be changed in a minor or patch release. See Cache versioning for more.
","path":["Reference","Policies","Versioning"],"tags":[]},{"location":"reference/policies/versioning/#lockfile-versioning","level":2,"title":"Lockfile versioning","text":"The uv.lock schema version is considered part of the public API, and so will only be incremented in a minor release as a breaking change. See Lockfile versioning for more.
","path":["Reference","Policies","Versioning"],"tags":[]},{"location":"reference/policies/versioning/#minimum-supported-rust-version","level":2,"title":"Minimum supported Rust version","text":"The minimum supported Rust version required to compile uv is listed in the rust-version key of the [workspace.package] section in Cargo.toml. It may change in any release (minor or patch). It will never be newer than N-2 Rust versions, where N is the latest stable version. For example, if the latest stable Rust version is 1.85, uv's minimum supported Rust version will be at most 1.83.
This is only relevant to users who build uv from source. Installing uv from the Python package index usually installs a pre-built binary and does not require Rust compilation.
","path":["Reference","Policies","Versioning"],"tags":[]},{"location":"reference/troubleshooting/","level":1,"title":"Troubleshooting","text":"The troubleshooting section provides information about investigating failures in uv:
- Build failures: Understanding common causes of package build failures.
- Reproducible examples: How to write a minimal reproducible example for a uv issue.
","path":["Reference","Troubleshooting"],"tags":[]},{"location":"reference/troubleshooting/build-failures/","level":1,"title":"Troubleshooting build failures","text":"uv needs to build packages when there is not a compatible wheel (a pre-built distribution of the package) available. Building packages can fail for many reasons, some of which may be unrelated to uv itself.
","path":["Reference","Troubleshooting","Troubleshooting build failures"],"tags":[]},{"location":"reference/troubleshooting/build-failures/#recognizing-a-build-failure","level":2,"title":"Recognizing a build failure","text":"An example build failure can be produced by trying to install and old version of numpy on a new, unsupported version of Python:
$ uv pip install -p 3.13 'numpy<1.20'\nResolved 1 package in 62ms\n × Failed to build `numpy==1.19.5`\n ├─▶ The build backend returned an error\n ╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel()` failed (exit status: 1)\n\n [stderr]\n Traceback (most recent call last):\n File \"<string>\", line 8, in <module>\n from setuptools.build_meta import __legacy__ as backend\n File \"/home/konsti/.cache/uv/builds-v0/.tmpi4bgKb/lib/python3.13/site-packages/setuptools/__init__.py\", line 9, in <module>\n import distutils.core\n ModuleNotFoundError: No module named 'distutils'\n\n hint: `distutils` was removed from the standard library in Python 3.12. Consider adding a constraint (like `numpy >1.19.5`) to avoid building a version of `numpy` that depends\n on `distutils`.\n
Notice that the error message is prefaced by \"The build backend returned an error\".
The build failure includes the [stderr] (and [stdout], if present) from the build backend that was used for the build. The error logs are not from uv itself.
The message following the ╰─▶ is a hint provided by uv, to help resolve common build failures. A hint will not be available for all build failures.
","path":["Reference","Troubleshooting","Troubleshooting build failures"],"tags":[]},{"location":"reference/troubleshooting/build-failures/#confirming-that-a-build-failure-is-specific-to-uv","level":2,"title":"Confirming that a build failure is specific to uv","text":"Build failures are usually related to your system and the build backend. It is rare that a build failure is specific to uv. You can confirm that the build failure is not related to uv by attempting to reproduce it with pip:
$ uv venv -p 3.13 --seed\n$ source .venv/bin/activate\n$ pip install --use-pep517 --no-cache --force-reinstall 'numpy==1.19.5'\nCollecting numpy==1.19.5\n Using cached numpy-1.19.5.zip (7.3 MB)\n Installing build dependencies ... done\n Getting requirements to build wheel ... done\nERROR: Exception:\nTraceback (most recent call last):\n ...\n File \"/Users/example/.cache/uv/archive-v0/3783IbOdglemN3ieOULx2/lib/python3.13/site-packages/pip/_vendor/pyproject_hooks/_impl.py\", line 321, in _call_hook\n raise BackendUnavailable(data.get('traceback', ''))\npip._vendor.pyproject_hooks._impl.BackendUnavailable: Traceback (most recent call last):\n File \"/Users/example/.cache/uv/archive-v0/3783IbOdglemN3ieOULx2/lib/python3.13/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py\", line 77, in _build_backend\n obj = import_module(mod_path)\n File \"/Users/example/.local/share/uv/python/cpython-3.13.0-macos-aarch64-none/lib/python3.13/importlib/__init__.py\", line 88, in import_module\n return _bootstrap._gcd_import(name[level:], package, level)\n ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n File \"<frozen importlib._bootstrap>\", line 1387, in _gcd_import\n File \"<frozen importlib._bootstrap>\", line 1360, in _find_and_load\n File \"<frozen importlib._bootstrap>\", line 1310, in _find_and_load_unlocked\n File \"<frozen importlib._bootstrap>\", line 488, in _call_with_frames_removed\n File \"<frozen importlib._bootstrap>\", line 1387, in _gcd_import\n File \"<frozen importlib._bootstrap>\", line 1360, in _find_and_load\n File \"<frozen importlib._bootstrap>\", line 1331, in _find_and_load_unlocked\n File \"<frozen importlib._bootstrap>\", line 935, in _load_unlocked\n File \"<frozen importlib._bootstrap_external>\", line 1022, in exec_module\n File \"<frozen importlib._bootstrap>\", line 488, in _call_with_frames_removed\n File \"/private/var/folders/6p/k5sd5z7j31b31pq4lhn0l8d80000gn/T/pip-build-env-vdpjme7d/overlay/lib/python3.13/site-packages/setuptools/__init__.py\", line 9, in <module>\n import distutils.core\nModuleNotFoundError: No module named 'distutils'\n
Important
The --use-pep517 flag should be included with the pip install invocation to ensure the same build isolation behavior. uv always uses build isolation by default.
We also recommend including the --force-reinstall and --no-cache options when reproducing failures.
Since this build failure occurs in pip too, it is not likely to be a bug with uv.
If a build failure is reproducible with another installer, you should investigate upstream (in this example, numpy or setuptools), find a way to avoid building the package in the first place, or make the necessary adjustments to your system for the build to succeed.
","path":["Reference","Troubleshooting","Troubleshooting build failures"],"tags":[]},{"location":"reference/troubleshooting/build-failures/#why-does-uv-build-a-package","level":2,"title":"Why does uv build a package?","text":"When generating the cross-platform lockfile, uv needs to determine the dependencies of all packages, even those only installed on other platforms. uv tries to avoid package builds during resolution. It uses any wheel if exist for that version, then tries to find static metadata in the source distribution (mainly pyproject.toml with static project.version, project.dependencies and project.optional-dependencies or METADATA v2.2+). Only if all of that fails, it builds the package.
When installing, uv needs to have a wheel for the current platform for each package. If no matching wheel exists in the index, uv tries to build the source distribution.
You can check which wheels exist for a PyPI project under “Download Files”, e.g. https://pypi.org/project/numpy/2.1.1.md#files. Wheels with ...-py3-none-any.whl filenames work everywhere, others have the operating system and platform in the filename. In the linked numpy example, you can see that there are pre-built distributions for Python 3.10 to 3.13 on macOS, Linux and Windows.
","path":["Reference","Troubleshooting","Troubleshooting build failures"],"tags":[]},{"location":"reference/troubleshooting/build-failures/#common-build-failures","level":2,"title":"Common build failures","text":"The following examples demonstrate common build failures and how to resolve them.
","path":["Reference","Troubleshooting","Troubleshooting build failures"],"tags":[]},{"location":"reference/troubleshooting/build-failures/#command-is-not-found","level":3,"title":"Command is not found","text":"If the build error mentions a missing command, for example, gcc:
× Failed to build `pysha3==1.0.2`\n├─▶ The build backend returned an error\n╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)\n\n [stdout]\n running bdist_wheel\n running build\n running build_py\n creating build/lib.linux-x86_64-cpython-310\n copying sha3.py -> build/lib.linux-x86_64-cpython-310\n running build_ext\n building '_pysha3' extension\n creating build/temp.linux-x86_64-cpython-310/Modules/_sha3\n gcc -Wno-unused-result -Wsign-compare -DNDEBUG -g -fwrapv -O3 -Wall -fPIC -DPY_WITH_KECCAK=1 -I/root/.cache/uv/builds-v0/.tmp8V4iEk/include -I/usr/local/include/python3.10 -c\n Modules/_sha3/sha3module.c -o build/temp.linux-x86_64-cpython-310/Modules/_sha3/sha3module.o\n\n [stderr]\n error: command 'gcc' failed: No such file or directory\n
Then, you'll need to install it with your system package manager, e.g., to resolve the error above:
$ apt install gcc\n
Tip
When using the uv-managed Python versions, it's common to need clang installed instead of gcc.
Many Linux distributions provide a package that includes all the common build dependencies. You can address most build requirements by installing it, e.g., for Debian or Ubuntu:
$ apt install build-essential\n
","path":["Reference","Troubleshooting","Troubleshooting build failures"],"tags":[]},{"location":"reference/troubleshooting/build-failures/#header-or-library-is-missing","level":3,"title":"Header or library is missing","text":"If the build error mentions a missing header or library, e.g., a .h file, then you'll need to install it with your system package manager.
For example, installing pygraphviz requires Graphviz to be installed:
× Failed to build `pygraphviz==1.14`\n├─▶ The build backend returned an error\n╰─▶ Call to `setuptools.build_meta.build_wheel` failed (exit status: 1)\n\n [stdout]\n running bdist_wheel\n running build\n running build_py\n ...\n gcc -fno-strict-overflow -Wsign-compare -DNDEBUG -g -O3 -Wall -fPIC -DSWIG_PYTHON_STRICT_BYTE_CHAR -I/root/.cache/uv/builds-v0/.tmpgLYPe0/include -I/usr/local/include/python3.12 -c pygraphviz/graphviz_wrap.c -o\n build/temp.linux-x86_64-cpython-312/pygraphviz/graphviz_wrap.o\n\n [stderr]\n ...\n pygraphviz/graphviz_wrap.c:9: warning: \"SWIG_PYTHON_STRICT_BYTE_CHAR\" redefined\n 9 | #define SWIG_PYTHON_STRICT_BYTE_CHAR\n |\n <command-line>: note: this is the location of the previous definition\n pygraphviz/graphviz_wrap.c:3023:10: fatal error: graphviz/cgraph.h: No such file or directory\n 3023 | #include \"graphviz/cgraph.h\"\n | ^~~~~~~~~~~~~~~~~~~\n compilation terminated.\n error: command '/usr/bin/gcc' failed with exit code 1\n\n hint: This error likely indicates that you need to install a library that provides \"graphviz/cgraph.h\" for `pygraphviz@1.14`\n
To resolve this error on Debian, you'd install the libgraphviz-dev package:
$ apt install libgraphviz-dev\n
Note that installing the graphviz package is not sufficient, the development headers need to be installed.
Tip
To resolve an error where Python.h is missing, install the python3-dev package.
","path":["Reference","Troubleshooting","Troubleshooting build failures"],"tags":[]},{"location":"reference/troubleshooting/build-failures/#module-is-missing-or-cannot-be-imported","level":3,"title":"Module is missing or cannot be imported","text":"If the build error mentions a failing import, consider disabling build isolation.
For example, some packages assume that pip is available without declaring it as a build dependency:
× Failed to build `chumpy==0.70`\n ├─▶ The build backend returned an error\n ╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)\n\n [stderr]\n Traceback (most recent call last):\n File \"<string>\", line 9, in <module>\n ModuleNotFoundError: No module named 'pip'\n\n During handling of the above exception, another exception occurred:\n\n Traceback (most recent call last):\n File \"<string>\", line 14, in <module>\n File \"/root/.cache/uv/builds-v0/.tmpvvHaxI/lib/python3.12/site-packages/setuptools/build_meta.py\", line 334, in get_requires_for_build_wheel\n return self._get_build_requires(config_settings, requirements=[])\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n File \"/root/.cache/uv/builds-v0/.tmpvvHaxI/lib/python3.12/site-packages/setuptools/build_meta.py\", line 304, in _get_build_requires\n self.run_setup()\n File \"/root/.cache/uv/builds-v0/.tmpvvHaxI/lib/python3.12/site-packages/setuptools/build_meta.py\", line 522, in run_setup\n super().run_setup(setup_script=setup_script)\n File \"/root/.cache/uv/builds-v0/.tmpvvHaxI/lib/python3.12/site-packages/setuptools/build_meta.py\", line 320, in run_setup\n exec(code, locals())\n File \"<string>\", line 11, in <module>\n ModuleNotFoundError: No module named 'pip'\n
To resolve this error, pre-install the build dependencies then disable build isolation for the package:
$ uv pip install pip setuptools\n$ uv pip install chumpy --no-build-isolation-package chumpy\n
Note you will need to install the missing package, e.g., pip, and all the other build dependencies of the package, e.g, setuptools.
","path":["Reference","Troubleshooting","Troubleshooting build failures"],"tags":[]},{"location":"reference/troubleshooting/build-failures/#old-version-of-the-package-is-built","level":3,"title":"Old version of the package is built","text":"If a package fails to build during resolution and the version that failed to build is older than the version you want to use, try adding a constraint with a lower bound (e.g., numpy>=1.17). Sometimes, due to algorithmic limitations, the uv resolver tries to find a fitting version using unreasonably old packages, which can be prevented by using lower bounds.
For example, when resolving the following dependencies on Python 3.10, uv attempts to build an old version of apache-beam.
requirements.txtdill<0.3.9,>=0.2.2\napache-beam<=2.49.0\n
× Failed to build `apache-beam==2.0.0`\n├─▶ The build backend returned an error\n╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)\n\n [stderr]\n ...\n
Adding a lower bound constraint, e.g., apache-beam<=2.49.0,>2.30.0, resolves this build failure as uv will avoid using an old version of apache-beam.
Constraints can also be defined for indirect dependencies using constraints.txt files or the constraint-dependencies setting.
","path":["Reference","Troubleshooting","Troubleshooting build failures"],"tags":[]},{"location":"reference/troubleshooting/build-failures/#old-version-of-a-build-dependency-is-used","level":3,"title":"Old Version of a build dependency is used","text":"If a package fails to build because uv selects an incompatible or outdated version of a build-time dependency, you can enforce constraints specifically for build dependencies. The build-constraint-dependencies setting (or an analogous build-constraints.txt file) can be used to ensure that uv selects an appropriate version of a given build requirements.
For example, the issue described in #5551 could be addressed by specifying a build constraint that excludes setuptools version 72.0.0:
pyproject.toml[tool.uv]\n# Prevent setuptools version 72.0.0 from being used as a build dependency.\nbuild-constraint-dependencies = [\"setuptools!=72.0.0\"]\n
The build constraint will thus ensure that any package requiring setuptools during the build process will avoid using the problematic version, preventing build failures caused by incompatible build dependencies.
","path":["Reference","Troubleshooting","Troubleshooting build failures"],"tags":[]},{"location":"reference/troubleshooting/build-failures/#package-is-only-needed-for-an-unused-platform","level":3,"title":"Package is only needed for an unused platform","text":"If locking fails due to building a package from a platform you do not need to support, consider limiting resolution to your supported platforms.
","path":["Reference","Troubleshooting","Troubleshooting build failures"],"tags":[]},{"location":"reference/troubleshooting/build-failures/#package-does-not-support-all-python-versions","level":3,"title":"Package does not support all Python versions","text":"If you support a large range of Python versions, consider using markers to use older versions for older Python versions and newer versions for newer Python version. For example, numpy only supports four Python minor version at a time, so to support a wider range of Python versions, e.g., Python 3.8 to 3.13, the numpy requirement needs to be split:
numpy>=1.23; python_version >= \"3.10\"\nnumpy<1.23; python_version < \"3.10\"\n
","path":["Reference","Troubleshooting","Troubleshooting build failures"],"tags":[]},{"location":"reference/troubleshooting/build-failures/#package-is-only-usable-on-a-specific-platform","level":3,"title":"Package is only usable on a specific platform","text":"If locking fails due to building a package that is only usable on another platform, you can provide dependency metadata manually to skip the build. uv can not verify this information, so it is important to specify correct metadata when using this override.
","path":["Reference","Troubleshooting","Troubleshooting build failures"],"tags":[]},{"location":"reference/troubleshooting/reproducible-examples/","level":1,"title":"Reproducible examples","text":"","path":["Reference","Troubleshooting","Reproducible examples"],"tags":[]},{"location":"reference/troubleshooting/reproducible-examples/#why-reproducible-examples-are-important","level":2,"title":"Why reproducible examples are important","text":"A minimal reproducible example (MRE) is essential for fixing bugs. Without an example that can be used to reproduce the problem, a maintainer cannot debug it or test if it is fixed. If the example is not minimal, i.e., if it includes lots of content which is not related to the issue, it can take a maintainer much longer to identify the root cause of the problem.
","path":["Reference","Troubleshooting","Reproducible examples"],"tags":[]},{"location":"reference/troubleshooting/reproducible-examples/#how-to-write-a-reproducible-example","level":2,"title":"How to write a reproducible example","text":"When writing a reproducible example, the goal is to provide all the context necessary for someone else to reproduce your example. This includes:
- The platform you're using (e.g., the operating system and architecture)
- Any relevant system state (e.g., explicitly set environment variables)
- The version of uv
- The version of other relevant tools
- The relevant files (the
uv.lock, pyproject.toml, etc.) - The commands to run
To ensure your reproduction is minimal, remove as many dependencies, settings, and files as possible. Be sure to test your reproduction before sharing it. We recommend including verbose logs from your reproduction; they may differ on your machine in a critical way. Using a Gist can be helpful for very long logs.
Below, we'll cover several specific strategies for creating and sharing reproducible examples.
Tip
There's a great guide to the basics of creating MREs on Stack Overflow.
","path":["Reference","Troubleshooting","Reproducible examples"],"tags":[]},{"location":"reference/troubleshooting/reproducible-examples/#strategies-for-reproducible-examples","level":2,"title":"Strategies for reproducible examples","text":"","path":["Reference","Troubleshooting","Reproducible examples"],"tags":[]},{"location":"reference/troubleshooting/reproducible-examples/#docker-image","level":3,"title":"Docker image","text":"Writing a Docker image is often the best way to share a reproducible example because it is entirely self-contained. This means that the state from the reproducer's system does not affect the problem.
Note
Using a Docker image is only feasible if the issue is reproducible on Linux. When using macOS, it's prudent to ensure your image is not reproducible on Linux but some bugs are specific to the operating system. While using Docker to run Windows containers is feasible, it's not commonplace. These sorts of bugs are expected to be reported as a script instead.
When writing a Docker MRE with uv, it's best to start with one of uv's Docker images. When doing so, be sure to pin to a specific version of uv.
FROM ghcr.io/astral-sh/uv:0.5.24-debian-slim\n
While Docker images are isolated from the system, the build will use your system's architecture by default. When sharing a reproduction, you can explicitly set the platform to ensure a reproducer gets the expected behavior. uv publishes images for linux/amd64 (e.g., Intel or AMD) and linux/arm64 (e.g., Apple M Series or ARM)
FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.5.24-debian-slim\n
Docker images are best for reproducing issues that can be constructed with commands, e.g.:
FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.5.24-debian-slim\n\nRUN uv init /mre\nWORKDIR /mre\nRUN uv add pydantic\nRUN uv sync\nRUN uv run -v python -c \"import pydantic\"\n
However, you can also write files into the image inline:
FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.5.24-debian-slim\n\nCOPY <<EOF /mre/pyproject.toml\n[project]\nname = \"example\"\nversion = \"0.1.0\"\ndescription = \"Add your description here\"\nreadme = \"README.md\"\nrequires-python = \">=3.12\"\ndependencies = [\"pydantic\"]\nEOF\n\nWORKDIR /mre\nRUN uv lock\n
If you need to write many files, it's better to create and publish a Git repository. You can combine these approaches and include a Dockerfile in the repository.
When sharing a Docker reproduction, it's helpful to include the build logs. You can see more output from the build steps by disabling caching and the fancy output:
docker build . --progress plain --no-cache\n
","path":["Reference","Troubleshooting","Reproducible examples"],"tags":[]},{"location":"reference/troubleshooting/reproducible-examples/#script","level":3,"title":"Script","text":"When reporting platform-specific bugs that cannot be reproduced in a container, it's best practice to include a script showing the commands that can be used to reproduce the bug, e.g.:
uv init\nuv add pydantic\nuv sync\nuv run -v python -c \"import pydantic\"\n
If your reproduction requires many files, use a Git repository to share them.
In addition to the script, include verbose logs (i.e., with the -v flag) of the failure and the complete error message.
Whenever a script relies on external state, be sure to share that information. For example, if you wrote the script on Windows, and it uses a Python version that you installed with choco and runs on PowerShell 6.2, please include that in the report.
","path":["Reference","Troubleshooting","Reproducible examples"],"tags":[]},{"location":"reference/troubleshooting/reproducible-examples/#git-repository","level":3,"title":"Git repository","text":"When sharing a Git repository reproduction, include a script that reproduces the problem or, even better, a Dockerfile. The first step of the script should be to clone the repository and checkout a specific commit:
$ git clone https://github.com/<user>/<project>.git\n$ cd <project>\n$ git checkout <commit>\n$ <commands to produce error>\n
You can quickly create a new repository in the GitHub UI or with the gh CLI:
$ gh repo create uv-mre-1234 --clone\n
When using a Git repository for a reproduction, please remember to minimize the contents by excluding files or settings that are not required to reproduce your problem.
","path":["Reference","Troubleshooting","Reproducible examples"],"tags":[]}]}
\ No newline at end of file
diff --git a/site/uv-next/sitemap.xml b/site/uv-next/sitemap.xml
new file mode 100644
index 000000000..029758e23
--- /dev/null
+++ b/site/uv-next/sitemap.xml
@@ -0,0 +1,222 @@
+
+
+
+ https://docs.astral.sh/uv/
+
+
+ https://docs.astral.sh/uv/getting-started/
+
+
+ https://docs.astral.sh/uv/getting-started/installation/
+
+
+ https://docs.astral.sh/uv/getting-started/first-steps/
+
+
+ https://docs.astral.sh/uv/getting-started/features/
+
+
+ https://docs.astral.sh/uv/getting-started/help/
+
+
+ https://docs.astral.sh/uv/guides/
+
+
+ https://docs.astral.sh/uv/guides/install-python/
+
+
+ https://docs.astral.sh/uv/guides/scripts/
+
+
+ https://docs.astral.sh/uv/guides/tools/
+
+
+ https://docs.astral.sh/uv/guides/projects/
+
+
+ https://docs.astral.sh/uv/guides/package/
+
+
+ https://docs.astral.sh/uv/guides/migration/
+
+
+ https://docs.astral.sh/uv/guides/migration/pip-to-project/
+
+
+ https://docs.astral.sh/uv/guides/integration/
+
+
+ https://docs.astral.sh/uv/guides/integration/docker/
+
+
+ https://docs.astral.sh/uv/guides/integration/jupyter/
+
+
+ https://docs.astral.sh/uv/guides/integration/marimo/
+
+
+ https://docs.astral.sh/uv/guides/integration/github/
+
+
+ https://docs.astral.sh/uv/guides/integration/gitlab/
+
+
+ https://docs.astral.sh/uv/guides/integration/pre-commit/
+
+
+ https://docs.astral.sh/uv/guides/integration/pytorch/
+
+
+ https://docs.astral.sh/uv/guides/integration/fastapi/
+
+
+ https://docs.astral.sh/uv/guides/integration/alternative-indexes/
+
+
+ https://docs.astral.sh/uv/guides/integration/dependency-bots/
+
+
+ https://docs.astral.sh/uv/guides/integration/aws-lambda/
+
+
+ https://docs.astral.sh/uv/guides/integration/coiled/
+
+
+ https://docs.astral.sh/uv/concepts/
+
+
+ https://docs.astral.sh/uv/concepts/projects/
+
+
+ https://docs.astral.sh/uv/concepts/projects/layout/
+
+
+ https://docs.astral.sh/uv/concepts/projects/init/
+
+
+ https://docs.astral.sh/uv/concepts/projects/dependencies/
+
+
+ https://docs.astral.sh/uv/concepts/projects/run/
+
+
+ https://docs.astral.sh/uv/concepts/projects/sync/
+
+
+ https://docs.astral.sh/uv/concepts/projects/config/
+
+
+ https://docs.astral.sh/uv/concepts/projects/build/
+
+
+ https://docs.astral.sh/uv/concepts/projects/workspaces/
+
+
+ https://docs.astral.sh/uv/concepts/tools/
+
+
+ https://docs.astral.sh/uv/concepts/python-versions/
+
+
+ https://docs.astral.sh/uv/concepts/configuration-files/
+
+
+ https://docs.astral.sh/uv/concepts/indexes/
+
+
+ https://docs.astral.sh/uv/concepts/resolution/
+
+
+ https://docs.astral.sh/uv/concepts/build-backend/
+
+
+ https://docs.astral.sh/uv/concepts/authentication/
+
+
+ https://docs.astral.sh/uv/concepts/authentication/cli/
+
+
+ https://docs.astral.sh/uv/concepts/authentication/http/
+
+
+ https://docs.astral.sh/uv/concepts/authentication/git/
+
+
+ https://docs.astral.sh/uv/concepts/authentication/certificates/
+
+
+ https://docs.astral.sh/uv/concepts/authentication/third-party/
+
+
+ https://docs.astral.sh/uv/concepts/cache/
+
+
+ https://docs.astral.sh/uv/concepts/preview/
+
+
+ https://docs.astral.sh/uv/pip/
+
+
+ https://docs.astral.sh/uv/pip/environments/
+
+
+ https://docs.astral.sh/uv/pip/packages/
+
+
+ https://docs.astral.sh/uv/pip/inspection/
+
+
+ https://docs.astral.sh/uv/pip/dependencies/
+
+
+ https://docs.astral.sh/uv/pip/compile/
+
+
+ https://docs.astral.sh/uv/pip/compatibility/
+
+
+ https://docs.astral.sh/uv/reference/
+
+
+ https://docs.astral.sh/uv/reference/cli/
+
+
+ https://docs.astral.sh/uv/reference/settings/
+
+
+ https://docs.astral.sh/uv/reference/environment/
+
+
+ https://docs.astral.sh/uv/reference/installer/
+
+
+ https://docs.astral.sh/uv/reference/troubleshooting/
+
+
+ https://docs.astral.sh/uv/reference/troubleshooting/build-failures/
+
+
+ https://docs.astral.sh/uv/reference/troubleshooting/reproducible-examples/
+
+
+ https://docs.astral.sh/uv/reference/internals/
+
+
+ https://docs.astral.sh/uv/reference/internals/resolver/
+
+
+ https://docs.astral.sh/uv/reference/benchmarks/
+
+
+ https://docs.astral.sh/uv/reference/policies/
+
+
+ https://docs.astral.sh/uv/reference/policies/versioning/
+
+
+ https://docs.astral.sh/uv/reference/policies/platforms/
+
+
+ https://docs.astral.sh/uv/reference/policies/license/
+
+
\ No newline at end of file
diff --git a/site/uv-next/stylesheets/extra.css b/site/uv-next/stylesheets/extra.css
new file mode 100644
index 000000000..fae94d5e9
--- /dev/null
+++ b/site/uv-next/stylesheets/extra.css
@@ -0,0 +1,686 @@
+:root {
+ --black: #261230;
+ --white: #ffffff;
+ --radiate: #d7ff64;
+ --flare: #6340ac;
+ --rock: #78876e;
+ --galaxy: #261230;
+ --space: #30173d;
+ --comet: #6f5d6f;
+ --cosmic: #de5fe9;
+ --sun: #ffac2f;
+ --electron: #46ebe1;
+ --aurora: #46eb74;
+ --constellation: #5f6de9;
+ --neutron: #cff3cf;
+ --proton: #f6afbc;
+ --nebula: #cdcbfb;
+ --supernova: #f1aff6;
+ --starlight: #f4f4f1;
+ --lunar: #fbf2fc;
+ --asteroid: #e3cee3;
+ --crater: #f0dfdf;
+}
+
+[data-md-color-scheme="astral-light"] {
+ --md-default-bg-color--dark: var(--black);
+ --md-default-bg-color--light: var(--white);
+ --md-default-fg-color--lightest: var(--white);
+ --md-primary-fg-color: var(--galaxy);
+ --md-typeset-a-color: var(--flare);
+ --md-accent-fg-color: var(--cosmic);
+}
+
+[data-md-color-scheme="astral-dark"] {
+ --md-default-bg-color: var(--galaxy);
+ --md-default-bg-color--light: var(--galaxy);
+ --md-default-fg-color: var(--white);
+ --md-default-fg-color--light: var(--white);
+ --md-default-fg-color--lighter: var(--white);
+ --md-default-fg-color--lightest: var(--black);
+ --md-primary-fg-color: var(--space);
+ --md-primary-bg-color: var(--white);
+ --md-accent-fg-color: var(--cosmic);
+
+ --md-typeset-color: var(--white);
+ --md-typeset-a-color: var(--radiate);
+ --md-typeset-mark-color: var(--sun);
+
+ --md-code-fg-color: var(--white);
+ --md-code-bg-color: var(--space);
+
+ --md-code-hl-comment-color: var(--asteroid);
+ --md-code-hl-punctuation-color: var(--asteroid);
+ --md-code-hl-generic-color: var(--supernova);
+ --md-code-hl-variable-color: var(--starlight);
+ --md-code-hl-string-color: var(--radiate);
+ --md-code-hl-keyword-color: var(--supernova);
+ --md-code-hl-operator-color: var(--supernova);
+ --md-code-hl-number-color: var(--electron);
+ --md-code-hl-special-color: var(--electron);
+ --md-code-hl-function-color: var(--neutron);
+ --md-code-hl-constant-color: var(--radiate);
+ --md-code-hl-name-color: var(--md-code-fg-color);
+
+ --md-typeset-del-color: hsla(6, 90%, 60%, 0.15);
+ --md-typeset-ins-color: hsla(150, 90%, 44%, 0.15);
+
+ --md-typeset-table-color: hsla(0, 0%, 100%, 0.12);
+ --md-typeset-table-color--light: hsla(0, 0%, 100%, 0.035);
+}
+
+[data-md-color-scheme="astral-light"] img[src$="#only-dark"],
+[data-md-color-scheme="astral-light"] img[src$="#gh-dark-mode-only"] {
+ display: none; /* Hide dark images in light mode */
+}
+
+[data-md-color-scheme="astral-light"] img[src$="#only-light"],
+[data-md-color-scheme="astral-light"] img[src$="#gh-light-mode-only"] {
+ display: inline; /* Show light images in light mode */
+}
+
+[data-md-color-scheme="astral-dark"] img[src$="#only-light"],
+[data-md-color-scheme="astral-dark"] img[src$="#gh-light-mode-only"] {
+ display: none; /* Hide light images in dark mode */
+}
+
+[data-md-color-scheme="astral-dark"] img[src$="#only-dark"],
+[data-md-color-scheme="astral-dark"] img[src$="#gh-dark-mode-only"] {
+ display: inline; /* Show dark images in dark mode */
+}
+
+/* See: https://github.com/squidfunk/mkdocs-material/issues/175#issuecomment-616694465 */
+.md-typeset__table {
+ min-width: 100%;
+}
+.md-typeset table:not([class]) {
+ display: table;
+}
+
+/* See: https://github.com/astral-sh/ruff/issues/8519 */
+[data-md-color-scheme="astral-dark"] details summary a {
+ color: var(--flare);
+}
+
+/* See: https://github.com/astral-sh/ruff/issues/9046 */
+[data-md-color-scheme="astral-dark"] div.admonition {
+ color: var(--md-code-fg-color);
+ background-color: var(--md-code-bg-color);
+}
+
+/* Prevent the shadow from the nav title from blurring the top link.
+The box shadow isn't really doing anything anyway.
+
+This is a consequence of the reduced nav spacing below. */
+.md-nav--primary .md-nav__title {
+ box-shadow: none;
+}
+
+/* Branding text styling - displayed next to logo on larger screens */
+.md-header__branding {
+ display: none;
+ align-items: center;
+ margin-left: 0.25rem; /* Even tighter spacing */
+ white-space: nowrap;
+}
+
+.md-header__branding-text {
+ font-size: 0.8125rem; /* Slightly smaller */
+ font-weight: 400;
+ color: var(--md-default-fg-color);
+ white-space: nowrap;
+}
+
+.md-header__branding-name {
+ font-weight: 700; /* Bold for "uv" */
+ margin-right: 0.2rem;
+}
+
+/* Show branding text only on larger screens */
+@media screen and (min-width: 76.25em) {
+ .md-header__branding {
+ display: flex;
+ }
+}
+
+/* Fix border color for footer */
+.md-footer {
+ border-top-color: rgba(0, 0, 0, 0.08);
+}
+/* Add a border to separate the meta footer from the other
+We do this because the background color is the same but the theme expects it to differ */
+.md-footer-meta {
+ border-top: 0.05rem solid rgba(0, 0, 0, 0.08);
+}
+
+/* Omits the nav title "uv" entirely unless on a small screen, in which case
+the nav title is needed for backwards navigation in the collapsible
+nav variant.
+
+See https://github.com/astral-sh/uv/issues/5130 */
+@media screen and (min-width: 76.25em) {
+ .md-nav__title {
+ display: none;
+ }
+}
+
+/* Always take the full screen for content, require scrolling to see the footer
+This stops the size of the nav from jumping around when you visit a page without
+a lot of content (i.e., an overview page). We don't apply this to sma screens
+because the nav is in a hamburger menu anyway
+*/
+@media screen and (min-width: 76.25em) {
+ .md-main {
+ min-height: 100vh;
+ }
+}
+
+/* See: https://mkdocstrings.github.io/recipes/#prevent-selection-of-prompts-and-output-in-python-code-blocks */
+.highlight .gp,
+.highlight .go {
+ /* Generic.Prompt, Generic.Output */
+ user-select: none;
+}
+
+/* Styling for the generated CLI reference page */
+.cli-reference dd {
+ margin-top: 0.1em;
+ margin-bottom: 0.5em;
+}
+.cli-reference dd p {
+ margin-block-start: 0.2em;
+ margin-block-end: 0.3em;
+}
+.cli-reference ul {
+ margin-bottom: 0.1em;
+}
+h3.cli-reference {
+ font-size: 1.1em;
+ margin: 0 0 0 0;
+}
+h3:has(+ p > small.added-in) {
+ display: inline-block;
+ margin: 0;
+}
+h3 + p:has(> small.added-in) {
+ display: inline;
+ margin: 0;
+}
+
+/* Styling for anchor link headers - using higher specificity instead of !important */
+.md-typeset .toclink,
+.md-typeset a.toclink {
+ color: unset;
+ text-decoration: none;
+}
+
+.md-typeset .toclink:hover,
+.md-typeset a.toclink:hover {
+ color: var(--md-accent-fg-color);
+ text-decoration: none;
+}
+
+/* Remove underlines from heading links - using higher specificity */
+.md-typeset h1 > a,
+.md-typeset h2 > a,
+.md-typeset h3 > a,
+.md-typeset h4 > a,
+.md-typeset h5 > a,
+.md-typeset h6 > a,
+.md-typeset h1 a.toclink,
+.md-typeset h2 a.toclink,
+.md-typeset h3 a.toclink,
+.md-typeset h4 a.toclink,
+.md-typeset h5 a.toclink,
+.md-typeset h6 a.toclink {
+ text-decoration: none;
+ border-bottom: none;
+}
+
+/* Omit the first breadcrumb item, which is the "Introduction" */
+.md-path__list > .md-path__item:first-of-type {
+ display: none;
+}
+.md-path__list > .md-path__item:nth-of-type(2):before {
+ display: none;
+}
+
+/* Hide the modified date — its positioning is awkward but will require theme
+modifications */
+.md-source-file__fact {
+ visibility: hidden;
+}
+
+/* Custom header navigation links styling */
+.md-header__nav-links {
+ display: flex;
+ align-items: center;
+ gap: 0.5rem; /* Reduced space between buttons */
+ flex-shrink: 0;
+}
+
+/* Tweak the formatting of the primary nav on a large screen */
+@media screen and (min-width: 76.25em) {
+ /* Increase the font size of the section headings */
+ .md-nav__item--section > .md-nav__link {
+ font-size: 0.85rem;
+ }
+ /* Increase the size of the first nav item to match the sections
+ It has no children, so it is not considered a section */
+ .md-nav--primary > .md-nav__list > .md-nav__item:first-of-type {
+ font-size: 0.85rem;
+ margin-bottom: 0.25em;
+ font-weight: bold;
+ }
+}
+
+/* Bold the active nav link for accessibility */
+.md-nav--primary .md-nav__item .md-nav__link--active {
+ font-weight: bold;
+}
+
+/* Styling for the custom header */
+
+/* Base icon button styles with CSS custom properties */
+.md-header__nav-link--icon {
+ --button-border-color: rgba(0, 0, 0, 0.08);
+ --button-hover-bg: rgba(0, 0, 0, 0.03);
+ --button-hover-border: rgba(0, 0, 0, 0.15);
+ --button-icon-color: rgba(0, 0, 0, 0.6);
+ --button-icon-hover-color: rgba(0, 0, 0, 0.85);
+
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ width: 1.875rem;
+ height: 1.75rem;
+ padding: 0;
+ background-color: transparent;
+ border: 1px solid var(--button-border-color);
+ border-radius: 0.5rem;
+ text-decoration: none;
+ transition: all 0.15s ease;
+}
+
+.md-header__nav-link--icon:hover {
+ background-color: var(--button-hover-bg);
+ border-color: var(--button-hover-border);
+}
+
+.md-header__nav-link--icon svg {
+ width: 16px;
+ height: 16px;
+ color: var(--button-icon-color);
+}
+
+.md-header__nav-link--icon:hover svg {
+ color: var(--button-icon-hover-color);
+}
+
+/* GitHub icon-only button with colored background */
+.md-header__nav-link--github {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ width: 1.875rem;
+ height: 1.75rem;
+ padding: 0;
+ background-color: var(--flare);
+ border: none;
+ border-radius: 0.5rem;
+ text-decoration: none;
+ transition: all 0.15s ease;
+}
+
+.md-header__nav-link--github:hover {
+ opacity: 0.9;
+ transform: translateY(-1px);
+}
+
+.md-header__nav-link--github svg {
+ width: 16px;
+ height: 16px;
+ color: white;
+ flex-shrink: 0;
+}
+
+/* Responsive adjustments for navigation links */
+@media screen and (max-width: 59.99em) {
+ .md-header__nav-links {
+ gap: 0.75rem;
+ }
+}
+
+/* Adjust header layout for better spacing */
+.md-header__inner {
+ display: flex;
+ align-items: center;
+ gap: 1rem;
+}
+
+/* Make header title less prominent to emphasize navigation */
+.md-header__title {
+ font-size: 1rem;
+ font-weight: 600;
+}
+
+/* Improve search button visibility */
+.md-header__button.md-icon[for="__search"] {
+ margin-left: auto;
+}
+
+/* Better spacing for color palette toggle */
+.md-header__option {
+ margin-left: 0.4rem;
+}
+
+/* Make search field more prominent and centered */
+@media screen and (min-width: 60em) {
+ .md-search__form {
+ background-color: var(--md-default-bg-color);
+ border: 1px solid var(--md-default-fg-color--lightest);
+ border-radius: 0.5rem;
+ box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
+ transition: all 0.2s ease;
+ }
+
+ .md-search__form:hover {
+ box-shadow: 0 4px 8px rgba(0, 0, 0, 0.08);
+ border-color: var(--md-primary-fg-color);
+ }
+
+ .md-search__form:focus-within {
+ box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12);
+ border-color: var(--md-accent-fg-color);
+ }
+
+ .md-search__input {
+ background-color: transparent;
+ font-size: 0.9rem;
+ }
+
+ .md-search__input::placeholder {
+ color: var(--md-default-fg-color--light);
+ opacity: 0.7;
+ }
+}
+
+/* Improve header responsiveness */
+@media screen and (max-width: 76.24999em) {
+ .md-header__title {
+ flex-shrink: 1;
+ }
+}
+
+/* Dark mode adjustments for search */
+[data-md-color-scheme="astral-dark"] .md-search__form {
+ background-color: var(--md-code-bg-color);
+ border-color: rgba(255, 255, 255, 0.1);
+}
+
+[data-md-color-scheme="astral-dark"] .md-search__form:hover {
+ border-color: var(--md-accent-fg-color);
+ box-shadow: 0 4px 8px rgba(0, 0, 0, 0.3);
+}
+
+[data-md-color-scheme="astral-dark"] .md-search__form:focus-within {
+ box-shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
+}
+
+/* Dark mode adjustments for icon buttons - using CSS custom properties */
+[data-md-color-scheme="astral-dark"] .md-header__nav-link--icon {
+ --button-border-color: rgba(255, 255, 255, 0.1);
+ --button-hover-bg: rgba(255, 255, 255, 0.05);
+ --button-hover-border: rgba(255, 255, 255, 0.2);
+ --button-icon-color: rgba(255, 255, 255, 0.6);
+ --button-icon-hover-color: rgba(255, 255, 255, 0.85);
+}
+
+/* Dark mode GitHub button */
+[data-md-color-scheme="astral-dark"] .md-header__nav-link--github {
+ background-color: var(--flare);
+}
+
+[data-md-color-scheme="astral-dark"] .md-header__nav-link--github:hover {
+ opacity: 0.85;
+}
+
+[data-md-color-scheme="astral-dark"] .md-header__nav-link--github svg {
+ color: white;
+}
+
+/* Prominent centered search bar styling */
+.md-header__search-container {
+ display: flex;
+ align-items: center;
+ flex: 1;
+ max-width: none;
+}
+
+.md-header__search-input {
+ display: flex;
+ align-items: center;
+ gap: 0.625rem;
+ width: 100%;
+ height: 1.875rem; /* 30px - even smaller */
+ padding: 0 0.75rem;
+ background-color: var(--md-default-bg-color);
+ border: 1px solid rgba(0, 0, 0, 0.06);
+ border-radius: 0.5rem;
+ cursor: pointer;
+ transition: all 0.15s ease;
+}
+
+.md-header__search-input:hover {
+ border-color: rgba(0, 0, 0, 0.12);
+ background-color: var(--md-default-bg-color);
+}
+
+.md-header__search-input svg {
+ flex-shrink: 0;
+ width: 14px;
+ height: 14px;
+ color: rgba(0, 0, 0, 0.4);
+}
+
+.md-header__search-placeholder {
+ flex: 1;
+ font-size: 0.75rem; /* Even smaller - 12px */
+ line-height: 1.25rem;
+ color: rgba(0, 0, 0, 0.45);
+ font-weight: 400;
+}
+
+.md-header__search-shortcut {
+ flex-shrink: 0;
+ padding: 0 0.25rem;
+ font-size: 0.625rem; /* Much smaller - 10px */
+ font-weight: 600;
+ color: rgba(0, 0, 0, 0.45);
+ /* No background - cleaner look */
+}
+
+/* Hide the default search modal trigger and modal positioning */
+.md-search {
+ position: fixed;
+}
+
+/* Dark mode search bar */
+[data-md-color-scheme="astral-dark"] .md-header__search-input {
+ background-color: var(--md-code-bg-color);
+ border: 1px solid rgba(255, 255, 255, 0.08);
+}
+
+[data-md-color-scheme="astral-dark"] .md-header__search-input:hover {
+ border-color: rgba(255, 255, 255, 0.15);
+}
+
+[data-md-color-scheme="astral-dark"] .md-header__search-input svg {
+ color: rgba(255, 255, 255, 0.4);
+}
+
+[data-md-color-scheme="astral-dark"] .md-header__search-placeholder {
+ color: rgba(255, 255, 255, 0.5);
+}
+
+[data-md-color-scheme="astral-dark"] .md-header__search-shortcut {
+ color: rgba(255, 255, 255, 0.5);
+}
+
+/* Header styling and border */
+.md-header {
+ box-shadow: 0 1px 0 0 rgba(0, 0, 0, 0.025); /* Very subtle shadow line */
+ border-bottom: none;
+ height: 3.5rem; /* Reduced header height */
+}
+
+.md-header nav {
+ height: 100%;
+}
+
+.md-header__inner {
+ height: 100%;
+ align-items: center;
+}
+
+[data-md-color-scheme="astral-dark"] .md-header {
+ box-shadow: 0 1px 0 0 rgba(255, 255, 255, 0.025);
+}
+
+@media screen and (min-width: 76.25em) {
+ /* Hide the search modal's button that appears in the header */
+ .md-search__button {
+ display: none;
+ }
+
+ .md-header__inner {
+ gap: 0.5rem;
+ padding: 0 1.5rem;
+ }
+
+ /* Hide the default title when we have custom centered search */
+ .md-header__title {
+ display: none;
+ }
+
+ /* Hide default search button - we have our custom centered one */
+ .md-header__button.md-icon[for="__search"] {
+ display: none;
+ }
+
+ /* Logo and branding - compact and left */
+ .md-header__button.md-logo {
+ flex-shrink: 0;
+ margin-right: 0;
+ }
+
+ .md-header__branding {
+ flex-shrink: 0;
+ margin-left: 0.4rem;
+ }
+
+ /* Search container - centered with max width */
+ .md-header__search-container {
+ order: 1; /* Move search to middle by putting it after other elements */
+ flex: 1;
+ display: flex;
+ justify-content: center;
+ margin: 0 2rem;
+ }
+
+ .md-header__search-input {
+ max-width: 500px; /* Limit search bar width */
+ }
+
+ /* Nav links aligned to the right */
+ .md-header__nav-links {
+ margin-left: auto;
+ order: 2; /* After search */
+ flex-shrink: 0;
+ }
+
+ /* Position color palette toggle */
+ .md-header__option {
+ order: 2; /* Same as nav links, will appear after them in DOM order */
+ margin-left: 0.5rem;
+ flex-shrink: 0;
+ }
+
+ /* Hide GitHub source component - we have it as a text link */
+ .md-header__source {
+ display: none;
+ }
+}
+
+/* Mobile layout adjustments */
+@media screen and (max-width: 76.24999em) {
+ .md-header__search-container {
+ display: none;
+ }
+
+ /* Remove gaps for manual spacing */
+ .md-header__inner {
+ gap: 0;
+ }
+
+ /* Nav links aligned to the right */
+ .md-header__nav-links {
+ margin-left: auto;
+ flex-shrink: 0;
+ }
+
+ /* Position color palette toggle */
+ .md-header__option {
+ margin-left: 0.5rem;
+ flex-shrink: 0;
+ }
+
+ /* Show and style mobile search button - inherits from icon button styles */
+ .md-header__button.md-icon[for="__search"] {
+ /* Inherits CSS custom properties from .md-header__nav-link--icon */
+ --button-border-color: rgba(0, 0, 0, 0.08);
+ --button-hover-bg: rgba(0, 0, 0, 0.03);
+ --button-hover-border: rgba(0, 0, 0, 0.15);
+ --button-icon-color: rgba(0, 0, 0, 0.6);
+ --button-icon-hover-color: rgba(0, 0, 0, 0.85);
+
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ width: 1.875rem;
+ height: 1.75rem;
+ padding: 0;
+ background-color: transparent;
+ border: 1px solid var(--button-border-color);
+ border-radius: 0.5rem;
+ margin-left: 0.5rem;
+ margin-right: 0.75rem; /* Extra spacing from Discord/GitHub */
+ flex-shrink: 0; /* Prevent button from squishing */
+ transition: all 0.15s ease;
+ }
+
+ .md-header__button.md-icon[for="__search"]:hover {
+ background-color: var(--button-hover-bg);
+ border-color: var(--button-hover-border);
+ }
+
+ .md-header__button.md-icon[for="__search"] svg {
+ width: 16px;
+ height: 16px;
+ color: var(--button-icon-color);
+ }
+
+ .md-header__button.md-icon[for="__search"]:hover svg {
+ color: var(--button-icon-hover-color);
+ }
+
+ /* Dark mode mobile search button - just override the CSS custom properties */
+ [data-md-color-scheme="astral-dark"]
+ .md-header__button.md-icon[for="__search"] {
+ --button-border-color: rgba(255, 255, 255, 0.1);
+ --button-hover-bg: rgba(255, 255, 255, 0.05);
+ --button-hover-border: rgba(255, 255, 255, 0.2);
+ --button-icon-color: rgba(255, 255, 255, 0.6);
+ --button-icon-hover-color: rgba(255, 255, 255, 0.85);
+ }
+}