CLI Reference

uv

An extremely fast Python package manager.

Usage

uv [OPTIONS] <COMMAND>

Commands

uv run: Run a command or script (experimental)
uv init: Create a new project (experimental)
uv add: Add dependencies to the project (experimental)
uv remove: Remove dependencies from the project (experimental)
uv sync: Update the project’s environment (experimental)
uv lock: Update the project’s lockfile (experimental)
uv tree: Display the project’s dependency tree (experimental)
uv tool: Run and install commands provided by Python packages (experimental)
uv python: Manage Python versions and installations (experimental)
uv pip: Manage Python packages with a pip-compatible interface
uv venv: Create a virtual environment
uv cache: Manage uv’s cache
uv version: Display uv’s version
uv help: Display documentation for a command

uv run

Run a command or script (experimental).

Ensures that the command runs in a Python environment.

When used with a file ending in .py, 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. If the script contains inline dependency metadata, it will be installed into an isolated, ephemeral environment.

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>

Options

--all-extras

Include 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.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--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.

--config-file config-file

The 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.

--config-setting, -C config-setting

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

--exclude-newer exclude-newer

Limit 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 UTC dates in the same format (e.g., 2006-12-02).

--extra extra

Include optional dependencies from the extra group 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

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.

--find-links, -f 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 (.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.

--frozen

Run 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.

--help, -h

Display the concise help for this command

--index-strategy 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-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

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

--index-url, -i 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

--isolated

Run the tool 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.

--keyring-provider 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.

Defaults to disabled.

Possible values:

disabled: Do not use keyring for credential lookup
subprocess: Use the keyring command for credential lookup

--link-mode 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.

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

--locked

Assert 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.

--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.

--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.

--no-binary-package no-binary-package

Don’t install pre-built wheels for a specific package

--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.

--no-build-isolation

Disable isolation when building source distributions.

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

--no-build-isolation-package 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.

--no-build-package no-build-package

Don’t build source distributions for a specific package

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-dev

Omit development dependencies.

This option is only available when running in a project.

--no-index

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

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-project

Avoid 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-downloads

Disable automatic downloads of Python

--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

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--package package

Run the command in a specific package in the workspace.

If not in a workspace, or if the workspace member does not exist, uv will exit with an error.

--prerelease 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).

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

--python, -p python

The 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.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall

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

--reinstall-package reinstall-package

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

--resolution 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).

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

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

Use 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, -V

Display the uv version

--with with

Run 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-requirements with-requirements

Run with all packages listed in the given requirements.txt files.

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 (experimental).

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]

Arguments

PATH

The path to use for the project.

Defaults to the current working directory. 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

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--name name

The name of the project.

Defaults to the name of the directory.

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--no-readme

Do not create a README.md file

--no-workspace

Avoid discovering a workspace.

Instead, create a standalone project.

By default, uv searches for workspaces in the current directory or any parent directory.

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python, -p python

The Python interpreter to use to determine the minimum supported Python version.

See uv python to view supported request formats.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--verbose, -v

Use 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, -V

Display the uv version

--virtual

Create a virtual workspace instead of a project.

A virtual workspace does not define project dependencies and cannot be published. Instead, workspace members declare project dependencies. Development dependencies may still be declared.

uv add

Add dependencies to the project (experimental).

Dependencies are added to the project's pyproject.toml file.

If no constraint or URL is provided for a dependency, a lower bound is added equal to the latest compatible version of the package, e.g., >=1.2.3, unless --frozen is provided, in which case no resolution is performed.

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] <REQUIREMENTS>...

Arguments

REQUIREMENTS: The packages to add, as PEP 508 requirements (e.g., ruff==0.5.0)

Options

--branch branch

Branch to use when adding a dependency from Git

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--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.

--config-file config-file

The 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.

--config-setting, -C config-setting

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

--dev

Add the requirements as development dependencies

--exclude-newer exclude-newer

Limit 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 UTC dates in the same format (e.g., 2006-12-02).

--extra extra

Extras to enable for the dependency.

May be provided more than once.

To add this dependency to an optional group in the current project instead, see --optional.

--extra-index-url 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

--find-links, -f 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 (.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.

--frozen

Add dependencies without re-locking the project.

The project environment will not be synced.

--help, -h

Display the concise help for this command

--index-strategy 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-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

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

--index-url, -i 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

--keyring-provider 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.

Defaults to disabled.

Possible values:

disabled: Do not use keyring for credential lookup
subprocess: Use the keyring command for credential lookup

--link-mode 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.

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

--locked

Assert 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.

--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.

--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.

--no-binary-package no-binary-package

Don’t install pre-built wheels for a specific package

--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.

--no-build-isolation

Disable isolation when building source distributions.

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

--no-build-isolation-package 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.

--no-build-package no-build-package

Don’t build source distributions for a specific package

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-editable

Don’t add the requirements as editables

--no-index

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

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--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

--no-sync

Avoid syncing the virtual environment after re-locking the project

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--optional optional

Add the requirements to the specified optional dependency group.

The group may then be activated when installing the project with the --extra flag.

To enable an optional dependency group for this requirement instead, see --extra.

--package package

Add the dependency to a specific package in the workspace

--prerelease 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).

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

--python, -p python

The Python interpreter to use for resolving and syncing.

See uv python for details on Python discovery and supported request formats.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--raw-sources

Add source requirements to project.dependencies, rather than tool.uv.sources.

By default, uv will use the tool.uv.sources section to record source information for Git, local, editable, and direct URL requirements.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall

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

--reinstall-package reinstall-package

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

--resolution 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).

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

--rev rev

Commit to use when adding a dependency from Git

--script script

Add 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 adhere 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 tag

Tag to use when adding a dependency from Git

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

Use 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, -V

Display the uv version

uv remove

Remove dependencies from the project (experimental).

Dependencies are removed from the project's pyproject.toml file.

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>...

Arguments

PACKAGES: The names of the dependencies to remove (e.g., ruff)

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--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.

--config-file config-file

The 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.

--config-setting, -C config-setting

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

--dev

Remove the packages from the development dependencies

--exclude-newer exclude-newer

Limit 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 UTC dates in the same format (e.g., 2006-12-02).

--extra-index-url 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

--find-links, -f 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 (.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.

--frozen

Remove dependencies without re-locking the project.

The project environment will not be synced.

--help, -h

Display the concise help for this command

--index-strategy 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-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

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

--index-url, -i 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

--keyring-provider 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.

Defaults to disabled.

Possible values:

disabled: Do not use keyring for credential lookup
subprocess: Use the keyring command for credential lookup

--link-mode 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.

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

--locked

Assert 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.

--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.

--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.

--no-binary-package no-binary-package

Don’t install pre-built wheels for a specific package

--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.

--no-build-isolation

Disable isolation when building source distributions.

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

--no-build-isolation-package 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.

--no-build-package no-build-package

Don’t build source distributions for a specific package

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-index

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

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--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

--no-sync

Avoid syncing the virtual environment after re-locking the project

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--optional optional

Remove the packages from the specified optional dependency group

--package package

Remove the dependencies from a specific package in the workspace

--prerelease 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).

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

--python, -p python

The Python interpreter to use for resolving and syncing.

See uv python for details on Python discovery and supported request formats.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall

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

--reinstall-package reinstall-package

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

--resolution 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).

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

--script script

Remove 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 adhere with PEP 723.

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

Use 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, -V

Display the uv version

uv sync

Update the project's environment (experimental).

Syncing ensures that all project dependencies are installed and up-to-date with the lockfile. Syncing also removes packages that are not declared as dependencies of the project.

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.

Usage

uv sync [OPTIONS]

Options

--all-extras

Include all optional dependencies

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--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.

--config-file config-file

The 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.

--config-setting, -C config-setting

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

--exclude-newer exclude-newer

Limit 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 UTC dates in the same format (e.g., 2006-12-02).

--extra extra

Include optional dependencies from the extra group name.

May be provided more than once.

--extra-index-url 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

--find-links, -f 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 (.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.

--frozen

Sync 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.

--help, -h

Display the concise help for this command

--index-strategy 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-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

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

--index-url, -i 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

--keyring-provider 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.

Defaults to disabled.

Possible values:

disabled: Do not use keyring for credential lookup
subprocess: Use the keyring command for credential lookup

--link-mode 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.

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

--locked

Assert 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.

--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.

--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.

--no-binary-package no-binary-package

Don’t install pre-built wheels for a specific package

--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.

--no-build-isolation

Disable isolation when building source distributions.

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

--no-build-isolation-package 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.

--no-build-package no-build-package

Don’t build source distributions for a specific package

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-clean

Do not remove extraneous packages.

When enabled, uv will make the minimum necessary changes to satisfy the requirements.

By default, syncing will remove any extraneous packages from the environment, unless --no-build-isolation is enabled, in which case extra packages are considered necessary for builds.

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-dev

Omit development dependencies

--no-index

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

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--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

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--package package

Sync for a specific package in the workspace.

The workspace’s environment (.venv) is updated to reflect the subset of dependencies declared by the specified workspace member package.

If not in a workspace, or if the workspace member does not exist, uv will exit with an error.

--prerelease 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).

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

--python, -p python

The 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.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall

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

--reinstall-package reinstall-package

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

--resolution 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).

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

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

Use 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, -V

Display the uv version

uv lock

Update the project's lockfile (experimental).

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]

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--config-setting, -C config-setting

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

--exclude-newer exclude-newer

Limit 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 UTC dates in the same format (e.g., 2006-12-02).

--extra-index-url 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

--find-links, -f 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 (.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.

--frozen

Assert that a uv.lock exists, without updating it

--help, -h

Display the concise help for this command

--index-strategy 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-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

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

--index-url, -i 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

--keyring-provider 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.

Defaults to disabled.

Possible values:

disabled: Do not use keyring for credential lookup
subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The 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.

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

--locked

Assert 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.

--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.

--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.

--no-binary-package no-binary-package

Don’t install pre-built wheels for a specific package

--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.

--no-build-isolation

Disable isolation when building source distributions.

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

--no-build-isolation-package 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.

--no-build-package no-build-package

Don’t build source distributions for a specific package

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-index

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

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--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

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--prerelease 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).

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

--python, -p python

The 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.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--resolution 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).

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

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

Use 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, -V

Display the uv version

uv tree

Display the project's dependency tree (experimental)

Usage

uv tree [OPTIONS]

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--config-setting, -C config-setting

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

--depth, -d depth

Maximum display depth of the dependency tree

[default: 255]

--exclude-newer exclude-newer

Limit 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 UTC dates in the same format (e.g., 2006-12-02).

--extra-index-url 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

--find-links, -f 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 (.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.

--frozen

Display the requirements without locking the project.

If the lockfile is missing, uv will exit with an error.

--help, -h

Display the concise help for this command

--index-strategy 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-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

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

--index-url, -i 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

--invert

Show 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-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.

Defaults to disabled.

Possible values:

disabled: Do not use keyring for credential lookup
subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The 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.

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

--locked

Assert 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.

--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.

--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.

--no-binary-package no-binary-package

Don’t install pre-built wheels for a specific package

--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.

--no-build-isolation

Disable isolation when building source distributions.

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

--no-build-isolation-package 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.

--no-build-package no-build-package

Don’t build source distributions for a specific package

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-dedupe

Do 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-index

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

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--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

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--package package

Display only the specified packages

--prerelease 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).

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

--prune prune

Prune the given package from the display of the dependency tree

--python, -p python

The 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.

--python-platform python-platform

The 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 aaarch64-apple-darwin.

Possible values:

windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
macos: An alias for aarch64-apple-darwin, the default target for macOS
x86_64-pc-windows-msvc: An x86 Windows target
x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_17
aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
x86_64-apple-darwin: An x86 macOS target
aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_17
aarch64-unknown-linux-musl: An ARM64 Linux target
x86_64-unknown-linux-musl: An x86_64 Linux target
x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--python-version python-version

The 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, -q

Do not print any output

--resolution 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).

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

--universal

Show 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, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

Use 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, -V

Display the uv version

uv tool

Run and install commands provided by Python packages (experimental)

Usage

uv tool [OPTIONS] <COMMAND>

Commands

uv tool run: Run a command provided by a Python package
uv tool install: Install commands provided by a Python package
uv tool upgrade: Upgrade installed tools
uv tool list: List installed tools
uv tool uninstall: Uninstall a tool
uv tool update-shell: Ensure that the tool executable directory is on the PATH
uv tool dir: Show 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 run ruff@0.3.0. If more complex version specification is desired or if the command is provided by a different package, use --from.

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

uv tool run [OPTIONS] [COMMAND]

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--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.

--config-file config-file

The 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.

--config-setting, -C config-setting

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

--exclude-newer exclude-newer

Limit 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 UTC dates in the same format (e.g., 2006-12-02).

--extra-index-url 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

--find-links, -f 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 (.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.

--from from

Use the given package to provide the command.

By default, the package name is assumed to match the command name.

--help, -h

Display the concise help for this command

--index-strategy 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-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

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

--index-url, -i 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

--isolated

Run the tool in an isolated virtual environment, ignoring any already-installed tools

--keyring-provider 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.

Defaults to disabled.

Possible values:

disabled: Do not use keyring for credential lookup
subprocess: Use the keyring command for credential lookup

--link-mode 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.

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

--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.

--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.

--no-binary-package no-binary-package

Don’t install pre-built wheels for a specific package

--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.

--no-build-isolation

Disable isolation when building source distributions.

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

--no-build-isolation-package 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.

--no-build-package no-build-package

Don’t build source distributions for a specific package

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-index

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

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--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

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--prerelease 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).

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

--python, -p python

The Python interpreter to use to build the run environment.

See uv python for details on Python discovery and supported request formats.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall

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

--reinstall-package reinstall-package

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

--resolution 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).

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

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

Use 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, -V

Display the uv version

--with with

Run with the given packages installed

--with-requirements with-requirements

Run with all packages listed in the given requirements.txt files

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

uv tool install [OPTIONS] <PACKAGE>

Arguments

PACKAGE: The package to install commands from

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--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.

--config-file config-file

The 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.

--config-setting, -C config-setting

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

--editable, -e

--exclude-newer exclude-newer

Limit 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 UTC dates in the same format (e.g., 2006-12-02).

--extra-index-url 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

--find-links, -f 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 (.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.

--force

Force installation of the tool.

Will replace any existing entry points with the same name in the executable directory.

--help, -h

Display the concise help for this command

--index-strategy 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-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

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

--index-url, -i 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

--keyring-provider 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.

Defaults to disabled.

Possible values:

disabled: Do not use keyring for credential lookup
subprocess: Use the keyring command for credential lookup

--link-mode 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.

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

--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.

--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.

--no-binary-package no-binary-package

Don’t install pre-built wheels for a specific package

--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.

--no-build-isolation

Disable isolation when building source distributions.

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

--no-build-isolation-package 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.

--no-build-package no-build-package

Don’t build source distributions for a specific package

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-index

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

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--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

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--prerelease 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).

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

--python, -p python

The Python interpreter to use to build the tool environment.

See uv python for details on Python discovery and supported request formats.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall

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

--reinstall-package reinstall-package

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

--resolution 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).

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

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

Use 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, -V

Display the uv version

--with with

Include the following extra requirements

--with-requirements with-requirements

Run all requirements listed in the given requirements.txt files

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

uv tool upgrade [OPTIONS] <NAME>

Arguments

NAME: The name of the tool to upgrade

Options

--all

Upgrade all tools

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--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.

--config-file config-file

The 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.

--config-setting, -C config-setting

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

--exclude-newer exclude-newer

Limit 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 UTC dates in the same format (e.g., 2006-12-02).

--extra-index-url 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

--find-links, -f 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 (.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.

--help, -h

Display the concise help for this command

--index-strategy 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-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

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

--index-url, -i 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

--keyring-provider 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.

Defaults to disabled.

Possible values:

disabled: Do not use keyring for credential lookup
subprocess: Use the keyring command for credential lookup

--link-mode 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.

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

--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.

--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.

--no-binary-package no-binary-package

Don’t install pre-built wheels for a specific package

--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.

--no-build-isolation

Disable isolation when building source distributions.

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

--no-build-isolation-package 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.

--no-build-package no-build-package

Don’t build source distributions for a specific package

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-index

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

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--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

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--prerelease 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).

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

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--reinstall

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

--reinstall-package reinstall-package

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

--resolution 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).

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

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

Use 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, -V

Display the uv version

uv tool list

List installed tools

Usage

uv tool list [OPTIONS]

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--quiet, -q

Do not print any output

--show-paths

Whether to display the path to each tool environment and installed executable

--verbose, -v

Use 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, -V

Display the uv version

uv tool uninstall

Uninstall a tool

Usage

uv tool uninstall [OPTIONS] <NAME>

Arguments

NAME: The name of the tool to uninstall

Options

--all

Uninstall all tools

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--verbose, -v

Use 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, -V

Display the uv version

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

uv tool update-shell [OPTIONS]

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--verbose, -v

Use 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, -V

Display the uv version

uv tool dir

Show the path to the uv tools directory.

The tools directory is used to store environments and metadata for installed tools.

To instead view the directory uv installs executables into, use the --bin flag.

Usage

uv tool dir [OPTIONS]

Options

--bin

Show 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.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--verbose, -v

Use 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, -V

Display the uv version

uv python

Manage Python versions and installations (experimental)

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 py launcher is also invoked to find Python executables.

When preview is enabled, i.e., via --preview or by using a preview command, uv will download Python if a version cannot be found. This behavior can be disabled with the --python-downloads option.

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
<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>

Commands

uv python list: List the available Python installations
uv python install: Download and install Python versions
uv python find: Search for a Python installation
uv python pin: Pin to a specific Python version
uv python dir: Show the uv Python installation directory
uv python uninstall: Uninstall Python versions

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.

The displayed versions are filtered by the --python-preference option, i.e., if using only-system, no managed Python versions will be shown.

Use --all-versions to view all available patch versions.

Use --only-installed to omit available downloads.

Usage

uv python list [OPTIONS]

Options

--all-platforms

List Python downloads for all platforms.

By default, only downloads for the current platform are shown.

--all-versions

List all Python versions, including old patch versions.

By default, only the latest patch version is shown for each minor version.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--only-installed

Only show installed Python versions, exclude available downloads.

By default, available downloads for the current platform are shown.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--verbose, -v

Use 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, -V

Display the uv version

uv python install

Download and install Python versions.

Multiple Python versions may be requested.

Supports CPython and PyPy.

CPython distributions are downloaded from the python-build-standalone project.

Python versions are installed into the uv Python directory, which can be retrieved with uv python dir. A python executable is not made globally available, managed Python versions are only used in uv commands or in active virtual environments.

See uv help python to view supported request formats.

Usage

uv python install [OPTIONS] [TARGETS]...

Arguments

TARGETS

The Python version(s) to install.

If not provided, the requested Python version(s) will be read from the .python-versions or .python-version files. If neither file is 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

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--reinstall, -r

Reinstall the requested Python version, if it’s already installed.

By default, uv will exit successfully if the version is already installed.

--verbose, -v

Use 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, -V

Display the uv version

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

uv python find [OPTIONS] [REQUEST]

Arguments

REQUEST

The Python request.

See uv python to view supported request formats.

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--verbose, -v

Use 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, -V

Display the uv version

uv python pin

Pin to a specific Python version.

Writes the pinned version to a .python-version file, which is then read by other uv commands when determining the required Python version.

See uv help python to view supported request formats.

Usage

uv python pin [OPTIONS] [REQUEST]

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.

See uv python to view supported request formats.

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--no-workspace

Avoid validating the Python pin is compatible with the workspace.

By default, a 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.

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--resolved

Write 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.

--verbose, -v

Use 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, -V

Display the uv version

uv python dir

Show the uv Python installation directory

Usage

uv python dir [OPTIONS]

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--verbose, -v

Use 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, -V

Display the uv version

uv python uninstall

Uninstall Python versions

Usage

uv python uninstall [OPTIONS] <TARGETS>...

Arguments

TARGETS

The Python version(s) to uninstall.

See uv python to view supported request formats.

Options

--all

Uninstall all managed Python versions

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--verbose, -v

Use 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, -V

Display the uv version

uv pip

Manage Python packages with a pip-compatible interface

Usage

uv pip [OPTIONS] <COMMAND>

Commands

uv pip compile: Compile a requirements.in file to a requirements.txt file
uv pip sync: Sync an environment with a requirements.txt file
uv pip install: Install packages into an environment
uv pip uninstall: Uninstall packages from an environment
uv pip freeze: List, in requirements format, packages installed in an environment
uv pip list: List, in tabular format, packages installed in an environment
uv pip show: Show information about one or more installed packages
uv pip tree: Display the dependency tree for an environment
uv pip check: Verify installed packages have compatible dependencies

uv pip compile

Compile a requirements.in file to a requirements.txt file

Usage

uv pip compile [OPTIONS] <SRC_FILE>...

Arguments

SRC_FILE

Include all packages listed in the given requirements.in files.

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-extras

Include all optional dependencies.

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

--annotation-style annotation-style

The 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 line
split: Render each annotation on its own line

--build-constraint, -b build-constraint

Constrain 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.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--config-setting, -C config-setting

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

--constraint, -c constraint

Constrain 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.

--custom-compile-command 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.

--emit-build-options

Include --no-binary and --only-binary entries in the generated output file

--emit-find-links

Include --find-links entries in the generated output file

--emit-index-annotation

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

--emit-index-url

Include --index-url and --extra-index-url entries in the generated output file

--exclude-newer exclude-newer

Limit 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 UTC dates in the same format (e.g., 2006-12-02).

--extra extra

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

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

--extra-index-url 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

--find-links, -f 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 (.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.

--generate-hashes

Include distribution hashes in the output file

--help, -h

Display the concise help for this command

--index-strategy 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-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

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

--index-url, -i 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

--keyring-provider 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.

Defaults to disabled.

Possible values:

disabled: Do not use keyring for credential lookup
subprocess: Use the keyring command for credential lookup

--legacy-setup-py

Use legacy setuptools behavior when building source distributions without a pyproject.toml

--link-mode link-mode

The 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.

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

--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.

--no-annotate

Exclude comment annotations indicating the source of each package

--no-binary 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:.

--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:.

--no-build-isolation

Disable isolation when building source distributions.

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

--no-build-isolation-package 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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-deps

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

--no-emit-package 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

--no-header

Exclude the comment header at the top of the generated output file

--no-index

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

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--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

--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.

--no-strip-markers

Include 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.

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--only-binary 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:.

--output-file, -o output-file

Write the compiled requirements 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.

--override override

Override 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.

--prerelease 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).

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

--python python

The 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.

See uv python for details on Python discovery and supported request formats.

--python-platform 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 aaarch64-apple-darwin.

Possible values:

windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
macos: An alias for aarch64-apple-darwin, the default target for macOS
x86_64-pc-windows-msvc: An x86 Windows target
x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_17
aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
x86_64-apple-darwin: An x86 macOS target
aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_17
aarch64-unknown-linux-musl: An ARM64 Linux target
x86_64-unknown-linux-musl: An x86_64 Linux target
x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--python-version, -p python-version

The 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, -q

Do not print any output

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--resolution 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).

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

--system

Install 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.

--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.

Implies --no-strip-markers.

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

Use 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, -V

Display the uv version

uv pip sync

Sync an environment with a requirements.txt file

Usage

uv pip sync [OPTIONS] <SRC_FILE>...

Arguments

SRC_FILE

Include all packages listed in the given requirements.txt files.

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

--allow-empty-requirements

Allow sync of empty requirements, which will clear the environment of all packages

--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).

--build-constraint, -b build-constraint

Constrain 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.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--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.

--config-file config-file

The 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.

--config-setting, -C config-setting

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

--constraint, -c constraint

Constrain 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.

--dry-run

Perform a dry run, i.e., don’t actually install anything but resolve the dependencies and print the resulting plan

--exclude-newer exclude-newer

Limit 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 UTC dates in the same format (e.g., 2006-12-02).

--extra-index-url 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

--find-links, -f 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 (.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.

--help, -h

Display the concise help for this command

--index-strategy 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-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

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

--index-url, -i 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

--keyring-provider 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.

Defaults to disabled.

Possible values:

disabled: Do not use keyring for credential lookup
subprocess: Use the keyring command for credential lookup

--legacy-setup-py

Use legacy setuptools behavior when building source distributions without a pyproject.toml

--link-mode 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.

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

--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.

--no-allow-empty-requirements

--no-binary 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:.

--no-break-system-packages

--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:.

--no-build-isolation

Disable isolation when building source distributions.

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

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-index

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

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--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

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--only-binary 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:.

--prefix 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.

--python, -p python

The Python interpreter into which packages should be installed.

By default, syncing requires a virtual environment. An 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.

--python-platform python-platform

The 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 aaarch64-apple-darwin.

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 Windows
linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
macos: An alias for aarch64-apple-darwin, the default target for macOS
x86_64-pc-windows-msvc: An x86 Windows target
x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_17
aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
x86_64-apple-darwin: An x86 macOS target
aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_17
aarch64-unknown-linux-musl: An ARM64 Linux target
x86_64-unknown-linux-musl: An x86_64 Linux target
x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--python-version python-version

The 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, -q

Do not print any output

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall

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

--reinstall-package reinstall-package

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

--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 installs 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.

--strict

Validate the Python environment after completing the installation, to detect and with missing dependencies or other issues

--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.

--target 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

--verbose, -v

Use 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>)

--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.

--version, -V

Display the uv version

uv pip install

Install packages into an environment

Usage

uv pip install [OPTIONS] <PACKAGE|--requirement <REQUIREMENT>|--editable <EDITABLE>>

Arguments

PACKAGE: Install all listed packages

Options

--all-extras

Include all optional dependencies.

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

--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).

--build-constraint, -b build-constraint

Constrain 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.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--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.

--config-file config-file

The 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.

--config-setting, -C config-setting

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

--constraint, -c constraint

Constrain 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.

--dry-run

Perform a dry run, i.e., don’t actually install anything but resolve the dependencies and print the resulting plan

--editable, -e editable

Install the editable package based on the provided local file path

--exclude-newer exclude-newer

Limit 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 UTC dates in the same format (e.g., 2006-12-02).

--extra extra

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

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

--extra-index-url 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

--find-links, -f 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 (.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.

--help, -h

Display the concise help for this command

--index-strategy 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-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

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

--index-url, -i 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

--keyring-provider 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.

Defaults to disabled.

Possible values:

disabled: Do not use keyring for credential lookup
subprocess: Use the keyring command for credential lookup

--legacy-setup-py

Use legacy setuptools behavior when building source distributions without a pyproject.toml

--link-mode 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.

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

--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.

--no-binary 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:.

--no-break-system-packages

--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:.

--no-build-isolation

Disable isolation when building source distributions.

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

--no-build-isolation-package 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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-deps

Ignore package dependencies, instead only installing those packages explicitly listed on the command line or in the requirements files

--no-index

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

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--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

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--only-binary 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:.

--override override

Override 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.

--prefix 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.

--prerelease 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).

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

--python, -p python

The Python interpreter into which packages should be installed.

By default, installation requires a virtual environment. An 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.

--python-platform python-platform

The 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 aaarch64-apple-darwin.

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 Windows
linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
macos: An alias for aarch64-apple-darwin, the default target for macOS
x86_64-pc-windows-msvc: An x86 Windows target
x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_17
aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
x86_64-apple-darwin: An x86 macOS target
aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_17
aarch64-unknown-linux-musl: An ARM64 Linux target
x86_64-unknown-linux-musl: An x86_64 Linux target
x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--python-version python-version

The 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, -q

Do not print any output

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall

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

--reinstall-package reinstall-package

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

--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 installs 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.

--requirement, -r requirement

Install all packages listed in the given requirements.txt files.

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 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).

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

--strict

Validate the Python environment after completing the installation, to detect and with missing dependencies or other issues

--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.

--target 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

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--user

--verbose, -v

Use 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>)

--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.

--version, -V

Display the uv version

uv pip uninstall

Uninstall packages from an environment

Usage

uv pip uninstall [OPTIONS] <PACKAGE|--requirement <REQUIREMENT>>

Arguments

PACKAGE: Uninstall all listed packages

Options

--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).

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--keyring-provider keyring-provider

Attempt 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.

Possible values:

disabled: Do not use keyring for credential lookup
subprocess: Use the keyring command for credential lookup

--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.

--no-break-system-packages

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--prefix prefix

Uninstall packages from the specified --prefix directory

--python, -p python

The Python interpreter from which packages should be uninstalled.

By default, uninstallation requires a virtual environment. An 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.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--requirement, -r requirement

Uninstall all packages listed in the given requirements files

--system

Use 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.

--target target

Uninstall packages from the specified --target directory

--verbose, -v

Use 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, -V

Display the uv version

uv pip freeze

List, in requirements format, packages installed in an environment

Usage

uv pip freeze [OPTIONS]

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--exclude-editable

Exclude any editable packages from output

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python, -p python

The 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.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--strict

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

--system

List packages in the system Python environment.

Disables discovery of virtual environments.

See uv python for details on Python discovery.

--verbose, -v

Use 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, -V

Display the uv version

uv pip list

List, in tabular format, packages installed in an environment

Usage

uv pip list [OPTIONS]

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--editable, -e

Only include editable projects

--exclude exclude

Exclude the specified package(s) from the output

--exclude-editable

Exclude any editable packages from output

--format format

Select the output format between: columns (default), freeze, or json

[default: columns]

Possible values:

columns: Display the list of packages in a human-readable table
freeze: Display the list of packages in a pip freeze-like format, with one package per line alongside its version
json: Display the list of packages in a machine-readable JSON format

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python, -p python

The 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.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--strict

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

--system

List packages in the system Python environment.

Disables discovery of virtual environments.

See uv python for details on Python discovery.

--verbose, -v

Use 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, -V

Display the uv version

uv pip show

Show information about one or more installed packages

Usage

uv pip show [OPTIONS] [PACKAGE]...

Arguments

PACKAGE: The package(s) to display

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python, -p python

The 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.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--strict

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

--system

Show a package in the system Python environment.

Disables discovery of virtual environments.

See uv python for details on Python discovery.

--verbose, -v

Use 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, -V

Display the uv version

uv pip tree

Display the dependency tree for an environment

Usage

uv pip tree [OPTIONS]

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--depth, -d depth

Maximum display depth of the dependency tree

[default: 255]

--help, -h

Display the concise help for this command

--invert

Show the reverse dependencies for the given package. This flag will invert the tree and display the packages that depend on the given package

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-dedupe

Do 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-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--no-system

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--package package

Display only the specified packages

--prune prune

Prune the given package from the display of the dependency tree

--python, -p python

The 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.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--show-version-specifiers

Show the version constraint(s) imposed on each package

--strict

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

--system

List packages in the system Python environment.

Disables discovery of virtual environments.

See uv python for details on Python discovery.

--verbose, -v

Use 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, -V

Display the uv version

uv pip check

Verify installed packages have compatible dependencies

Usage

uv pip check [OPTIONS]

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python, -p python

The 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.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--system

Check packages in the system Python environment.

Disables discovery of virtual environments.

See uv python for details on Python discovery.

--verbose, -v

Use 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, -V

Display the uv version

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 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] [NAME]

Arguments

NAME: The path to the virtual environment to create

Options

--allow-existing

Preserve any existing files or directories at the target path.

By default, uv venv will remove an existing virtual environment at the given path, and exit with an error if the path is non-empty but not a virtual environment. 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.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--exclude-newer exclude-newer

Limit 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 UTC dates in the same format (e.g., 2006-12-02).

--extra-index-url 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 (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

--find-links, -f 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 (.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.

--help, -h

Display the concise help for this command

--index-strategy 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-match). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary.

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

--index-url, -i 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 given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

--keyring-provider 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.

Defaults to disabled.

Possible values:

disabled: Do not use keyring for credential lookup
subprocess: Use the keyring command for credential lookup

--link-mode link-mode

The 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.

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

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-index

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

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--prompt prompt

Provide 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 the current directory name will be used regardless of whether a path was provided to uv venv.

--python, -p python

The 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 help for details on Python discovery and supported request formats.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--relocatable

Make 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.

--seed

Install seed packages (one or more of: pip, setuptools, and wheel) into the virtual environment.

Note setuptools and wheel are not included in Python 3.12+ environments.

--system-site-packages

Give 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, -v

Use 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, -V

Display the uv version

uv cache

Manage uv's cache

Usage

uv cache [OPTIONS] <COMMAND>

Commands

uv cache clean: Clear the cache, removing all entries or those linked to specific packages
uv cache prune: Prune all unreachable objects from the cache
uv cache dir: Show the cache directory

uv cache clean

Clear the cache, removing all entries or those linked to specific packages

Usage

uv cache clean [OPTIONS] [PACKAGE]...

Arguments

PACKAGE: The packages to remove from the cache

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--verbose, -v

Use 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, -V

Display the uv version

uv cache prune

Prune all unreachable objects from the cache

Usage

uv cache prune [OPTIONS]

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--ci

Optimize 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-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--verbose, -v

Use 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, -V

Display the uv version

uv cache dir

Show the cache directory

Usage

uv cache dir [OPTIONS]

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--verbose, -v

Use 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, -V

Display the uv version

uv version

Display uv's version

Usage

uv version [OPTIONS]

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--output-format output-format

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--verbose, -v

Use 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, -V

Display the uv version

uv help

Display documentation for a command

Usage

uv help [OPTIONS] [COMMAND]...

Arguments

COMMAND

Options

--cache-dir cache-dir

Path to the cache directory.

Defaults to $HOME/Library/Caches/uv on macOS, $XDG_CACHE_HOME/uv or $HOME/.cache/uv on Linux, and {FOLDERID_LocalAppData}\uv\cache on Windows.

--color color-choice

Control colors in output

[default: auto]

Possible values:

auto: Enables colored output only when the output is going to a terminal or TTY with support
always: Enables colored output regardless of the detected environment
never: Disables colored output

--config-file config-file

The 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.

--help, -h

Display the concise help for this command

--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.

--no-cache, -n

Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation

--no-config

Avoid discovering configuration files (pyproject.toml, uv.toml).

Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.

--no-pager

Disable pager when printing help

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

--no-python-downloads

Disable automatic downloads of Python

--offline

Disable network access.

When disabled, uv will only use locally cached data and locally available files.

--python-preference python-preference

Whether to prefer uv-managed or system Python installations.

By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python installations.

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

--quiet, -q

Do not print any output

--verbose, -v

Use 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, -V

Display the uv version

Files

cli.md

Latest commit

History

cli.md

File metadata and controls

CLI Reference

uv

Usage

Commands

uv run

Usage

Options

uv init

Usage

Arguments

Options

uv add

Usage

Arguments

Options

uv remove

Usage

Arguments

Options

uv sync

Usage

Options

uv lock

Usage

Options

uv tree

Usage

Options

uv tool

Usage

Commands

uv tool run

Usage

Options

uv tool install

Usage

Arguments

Options

uv tool upgrade

Usage

Arguments

Options

uv tool list

Usage

Options

uv tool uninstall

Usage

Arguments

Options

uv tool update-shell

Usage

Options

uv tool dir

Usage

Options

uv python

Usage

Commands

uv python list

Usage

Options

uv python install

Usage

Arguments

Options

uv python find

Usage

Arguments

Options

uv python pin

Usage

Arguments

Options

uv python dir