mirrors/uv

mirror of https://github.com/astral-sh/uv.git synced 2025-08-04 02:48:17 +00:00

Improve CLI documentation for uv run (#5841 )

Adds more long-form help to `uv run`, which renders in `uv help run` and
the CLI reference on the website.

2024-08-07 13:26:24 +00:00

206 KiB

Raw Blame History

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

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

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

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

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

--upgrade-package, -P upgrade-package

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

--reinstall-package reinstall-package

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

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

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

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

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

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

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

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

Don’t build source distributions for a specific package

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

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

--refresh-package refresh-package

Refresh cached data for a specific package

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

--python, -p python

The Python interpreter to use to build the run 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 --python option allows you to specify a different interpreter.

Supported formats:

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

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

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

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv init

Create a new project (experimental)

Usage

uv init [OPTIONS] [PATH]

Arguments

PATH: The path of the project

Options

--name name

The name of the project, defaults to the name of the directory

--python, -p python

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

Supported formats:

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv add

Add dependencies to the project (experimental)

Usage

uv add [OPTIONS] <REQUIREMENTS>...

Arguments

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

Options

--optional optional

Add the requirements to the specified optional dependency group

--rev rev

Specific commit to use when adding from Git

--tag tag

Tag to use when adding from git

--branch branch

Branch to use when adding from git

--extra extra

Extras to activate for the dependency; may be provided more than once

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

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

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

--upgrade-package, -P upgrade-package

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

--reinstall-package reinstall-package

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

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

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

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

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

--prerelease prerelease

The strategy to use when considering pre-release versions.

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

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

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

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

Don’t build source distributions for a specific package

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

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

--refresh-package refresh-package

Refresh cached data for a specific package

--package package

Add the dependency to a specific package in the workspace

--python, -p python

The Python interpreter into which packages should be installed.

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

Supported formats:

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv remove

Remove dependencies from the project (experimental)

Usage

uv remove [OPTIONS] <REQUIREMENTS>...

Arguments

REQUIREMENTS: The names of the packages to remove (e.g., ruff)

Options

--optional optional

Remove the requirements from the specified optional dependency group

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

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

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

--upgrade-package, -P upgrade-package

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

--reinstall-package reinstall-package

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

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

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

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

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

--prerelease prerelease

The strategy to use when considering pre-release versions.

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

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

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

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

Don’t build source distributions for a specific package

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

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

--refresh-package refresh-package

Refresh cached data for a specific package

--package package

Remove the dependency from a specific package in the workspace

--python, -p python

The Python interpreter into which packages should be installed.

Supported formats:

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv sync

Update the project's environment (experimental)

Usage

uv sync [OPTIONS]

Options

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

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

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

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

--upgrade-package, -P upgrade-package

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

--reinstall-package reinstall-package

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

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

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

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

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

--prerelease prerelease

The strategy to use when considering pre-release versions.

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

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

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

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

Don’t build source distributions for a specific package

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

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

--refresh-package refresh-package

Refresh cached data for a specific package

--package package

Sync a specific package in the workspace

--python, -p python

The Python interpreter to use to build the run environment.

Supported formats:

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv lock

Update the project's lockfile (experimental)

Usage

uv lock [OPTIONS]

Options

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

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

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

--upgrade-package, -P upgrade-package

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

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

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

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

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

--prerelease prerelease

The strategy to use when considering pre-release versions.

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

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

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

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

Don’t build source distributions for a specific package

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

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

--refresh-package refresh-package

Refresh cached data for a specific package

--python, -p python

The Python interpreter to use to build the run environment.

Supported formats:

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv tree

Display the project's dependency tree (experimental)

Usage

uv tree [OPTIONS]

Options

--depth, -d depth

Maximum display depth of the dependency tree

[default: 255]

--prune prune

Prune the given package from the display of the dependency tree

--package package

Display only the specified packages

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

Don’t build source distributions for a specific package

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

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

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

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

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

--upgrade-package, -P upgrade-package

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

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

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

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

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

--prerelease prerelease

The strategy to use when considering pre-release versions.

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

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

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

--python-version python-version

The Python version to use when filtering the tree (via --filter). For example, pass --python-version 3.10 to display the dependencies that would be included when installing on Python 3.10

--python-platform python-platform

The platform to use when filtering the tree (via --filter). 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, -p python

The Python interpreter for which packages should be listed.

Supported formats:

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv tool

Run and manage tools provided by Python packages (experimental)

Usage

uv tool [OPTIONS] <COMMAND>

Commands

uv tool run: Run a tool
uv tool install: Install a tool
uv tool list: List installed tools
uv tool uninstall: Uninstall a tool
uv tool update-shell: Ensure that the tool executable directory is on PATH
uv tool dir: Show the tools directory

uv tool run

Run a tool

Usage

uv tool run [OPTIONS] [COMMAND]

Options

--from from

Use the given package to provide the command.

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

--with with

Run with the given packages installed

--with-requirements with-requirements

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

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

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

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

--upgrade-package, -P upgrade-package

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

--reinstall-package reinstall-package

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

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

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

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

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

--prerelease prerelease

The strategy to use when considering pre-release versions.

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

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

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

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

Don’t build source distributions for a specific package

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

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

--refresh-package refresh-package

Refresh cached data for a specific package

--python, -p python

The Python interpreter to use to build the run environment.

Supported formats:

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv tool install

Install a tool

Usage

uv tool install [OPTIONS] <PACKAGE>

Arguments

PACKAGE: The package to install commands from

Options

--with with

Include the following extra requirements

--with-requirements with-requirements

Run all requirements listed in the given requirements.txt files

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

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

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

--upgrade-package, -P upgrade-package

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

--reinstall-package reinstall-package

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

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

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

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

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

--prerelease prerelease

The strategy to use when considering pre-release versions.

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

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

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

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

Don’t build source distributions for a specific package

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

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

--refresh-package refresh-package

Refresh cached data for a specific package

--python, -p python

The Python interpreter to use to build the tool environment.

By default, uv will search for a Python executable in the PATH. uv ignores virtual environments while looking for interpreter for tools. The --python option allows you to specify a different interpreter.

Supported formats:

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

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.

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv tool uninstall

Uninstall a tool

Usage

uv tool uninstall [OPTIONS] <NAME>

Arguments

NAME: The name of the tool to uninstall

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.

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv tool update-shell

Ensure that the tool executable directory is on PATH

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.

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv tool dir

Show the tools directory

Usage

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv python

Manage Python versions and installations (experimental)

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

Usage

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv python install

Download and install Python versions

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.

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.

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv python find

Search for a Python installation

Usage

uv python find [OPTIONS] [REQUEST]

Arguments

REQUEST: The Python request

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.

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv python pin

Pin to a specific Python version

Usage

uv python pin [OPTIONS] [REQUEST]

Arguments

REQUEST: The Python version

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.

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

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.

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv python uninstall

Uninstall Python versions

Usage

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

Arguments

TARGETS: The Python version(s) to uninstall

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.

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

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

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

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

--build-constraint, -b build-constraint

Constrain build dependencies using the given requirements files when building source distributions.

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

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

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

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

--upgrade-package, -P upgrade-package

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

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

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

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

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

--prerelease prerelease

The strategy to use when considering pre-release versions.

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

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

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

--refresh-package refresh-package

Refresh cached data for a specific package

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

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

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

--python python

The Python interpreter against which to compile the requirements.

Supported formats:

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

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

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

--python-version, -p python-version

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

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

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

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

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

--constraint, -c constraint

Constrain versions using the given requirements files.

This is equivalent to pip’s --constraint option.

--build-constraint, -b build-constraint

Constrain build dependencies using the given requirements files when building source distributions.

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

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

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

--reinstall-package reinstall-package

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

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

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

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

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

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

--refresh-package refresh-package

Refresh cached data for a specific package

--python, -p python

The Python interpreter into which packages should be installed.

Supported formats:

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

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

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

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

--only-binary only-binary

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

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

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

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

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

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

--editable, -e editable

Install the editable package based on the provided local file path

--constraint, -c constraint

Constrain versions using the given requirements files.

This is equivalent to pip’s --constraint option.

--override override

Override versions using the given requirements files.

--build-constraint, -b build-constraint

Constrain build dependencies using the given requirements files when building source distributions.

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

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

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

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

--upgrade-package, -P upgrade-package

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

--reinstall-package reinstall-package

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

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

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

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

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

--prerelease prerelease

The strategy to use when considering pre-release versions.

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

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

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

--refresh-package refresh-package

Refresh cached data for a specific package

--python, -p python

The Python interpreter into which packages should be installed.

Supported formats:

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

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

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

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

--only-binary only-binary

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

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

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

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

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv pip uninstall

Uninstall packages from an environment

Usage

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

Arguments

PACKAGE: Uninstall all listed packages

Options

--requirement, -r requirement

Uninstall all packages listed in the given requirements files

--python, -p python

The Python interpreter from which packages should be uninstalled.

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

Supported formats:

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

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

--target target

Uninstall packages from the specified --target directory

--prefix prefix

Uninstall packages from the specified --prefix directory

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv pip freeze

List, in requirements format, packages installed in an environment

Usage

uv pip freeze [OPTIONS]

Options

--python, -p python

The Python interpreter for which packages should be listed.

By default, uv lists packages in the currently activated virtual environment, or a virtual environment (.venv) located in the current working directory or any parent directory, falling back to the system Python if no virtual environment is found.

Supported formats:

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv pip list

List, in tabular format, packages installed in an environment

Usage

uv pip list [OPTIONS]

Options

--exclude exclude

Exclude the specified package(s) from the 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

--python, -p python

The Python interpreter for which packages should be listed.

Supported formats:

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

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

--python, -p python

The Python interpreter for which packages should be listed.

Supported formats:

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv pip tree

Display the dependency tree for an environment

Usage

uv pip tree [OPTIONS]

Options

--depth, -d depth

Maximum display depth of the dependency tree

[default: 255]

--prune prune

Prune the given package from the display of the dependency tree

--package package

Display only the specified packages

--python, -p python

The Python interpreter for which packages should be listed.

Supported formats:

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv pip check

Verify installed packages have compatible dependencies

Usage

uv pip check [OPTIONS]

Options

--python, -p python

The Python interpreter for which packages should be listed.

Supported formats:

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv venv

Create a virtual environment

Usage

uv venv [OPTIONS] [NAME]

Arguments

NAME: The path to the virtual environment to create

Options

--python, -p python

The Python interpreter to use for the virtual environment.

Supported formats:

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

Note that this is different from --python-version in pip compile, which takes 3.10 or 3.10.13 and doesn’t look for a Python interpreter on disk.

--prompt prompt

Provide an alternative prompt prefix for the virtual environment.

The default behavior depends on whether the virtual environment path is provided:

If provided (uv venv project), the prompt is set to the virtual environment’s directory name.
If not provided (uv venv), the prompt is set to the current directory’s name.

Possible values:

.: Use the current directory name.
Any string: Use the given string.

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

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

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

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

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

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

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

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

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

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.

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

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.

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

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.

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

uv version

Display uv's version

Usage

uv version [OPTIONS]

Options

--output-format output-format

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

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

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.

--python-preference python-preference

Whether to prefer uv-managed or 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-fetch python-fetch

Whether to automatically download Python when required

Possible values:

automatic: Automatically fetch managed Python installations when needed
manual: Do not automatically fetch managed Python installations; require explicit installation

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

206 KiB Raw Blame History Unescape Escape

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

Usage

Options

uv python uninstall

Usage

Arguments

Options

uv pip

Usage

Commands

206 KiB

Raw Blame History