diff --git a/crates/uv-dev/src/generate_cli_reference.rs b/crates/uv-dev/src/generate_cli_reference.rs index 7beac5963..8388ad191 100644 --- a/crates/uv-dev/src/generate_cli_reference.rs +++ b/crates/uv-dev/src/generate_cli_reference.rs @@ -199,21 +199,18 @@ fn generate_command<'a>(output: &mut String, command: &'a Command, parents: &mut output.push_str("\n\n"); } - // Display options + // Display options and flags let mut options = command - .get_opts() + .get_arguments() + .filter(|arg| !arg.is_positional()) .filter(|arg| !arg.is_hide_set()) - .sorted_by_key(|opt| opt.get_id()) + .sorted_by_key(|arg| arg.get_id()) .peekable(); if options.peek().is_some() { output.push_str("

Options

\n\n"); output.push_str("
"); - for opt in command.get_opts() { - if opt.is_hide_set() { - continue; - } - + for opt in options { let Some(long) = opt.get_long() else { continue }; output.push_str("
"); @@ -221,12 +218,20 @@ fn generate_command<'a>(output: &mut String, command: &'a Command, parents: &mut if let Some(short) = opt.get_short() { output.push_str(&format!(", -{short}")); } - if let Some(values) = opt.get_value_names() { - for value in values { - output.push_str(&format!( - " {}", - value.to_lowercase().replace('_', "-") - )); + + // Re-implements private `Arg::is_takes_value_set` used in `Command::get_opts` + if opt + .get_num_args() + .unwrap_or_else(|| 1.into()) + .takes_values() + { + if let Some(values) = opt.get_value_names() { + for value in values { + output.push_str(&format!( + " {}", + value.to_lowercase().replace('_', "-") + )); + } } } output.push_str("
"); diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 66652a929..b418862f1 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -64,7 +64,45 @@ uv run [OPTIONS]

Options

-
--extra extra

Include optional dependencies from the extra group name.

+
--all-extras

Include all optional dependencies.

+ +

Optional dependencies are defined via project.optional-dependencies in a pyproject.toml.

+ +

This option is only available when running in a project.

+ +
--cache-dir cache-dir

Path to the cache directory.

+ +

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

+ +
--color color-choice

Control colors in output

+ +

[default: auto]

+

Possible values:

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

Compile Python files to bytecode after installation.

+ +

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

+ +

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

+ +
--config-file config-file

The path to a uv.toml file to use for configuration.

+ +

While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

+ +
--config-setting, -C config-setting

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

+ +
--exclude-newer exclude-newer

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

+ +

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

+ +
--extra extra

Include optional dependencies from the extra group name.

May be provided more than once.

@@ -72,22 +110,6 @@ uv run [OPTIONS]

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.

@@ -100,9 +122,11 @@ uv run [OPTIONS]

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

+
--frozen

Run without updating the uv.lock file.

-
--reinstall-package reinstall-package

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

+

Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the pyproject.toml includes new dependencies that have not been included in the lockfile yet, they will not be present in the environment.

+ +
--help, -h

Display the concise help for this command

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

@@ -117,6 +141,20 @@ uv run [OPTIONS]
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • +
    --index-url, -i index-url

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

    + +

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

    + +

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    + +
    --isolated

    Run the tool in an isolated virtual environment.

    + +

    Usually, the project environment is reused for performance. This option forces a fresh environment to be used for the project, enforcing strict isolation between dependencies and declaration of requirements.

    + +

    An editable installation is still used for the project.

    + +

    When used with --with or --with-requirements, the additional dependencies will still be layered in a second environment.

    +
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

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

    @@ -130,19 +168,83 @@ uv run [OPTIONS]
  • 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.

    +
    --link-mode link-mode

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

    -

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

    +

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

    Possible values:

      -
    • highest: Resolve the highest compatible version of each package
      • +
    • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
      • -
    • lowest: Resolve the lowest compatible version of each package
      • +
    • copy: Copy packages from the wheel into the site-packages directory
      • -
    • lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
      • +
    • hardlink: Hard link packages from the wheel into the site-packages directory
      • + +
    • symlink: Symbolically link packages from the wheel into the site-packages directory
    +
    --locked

    Assert that the uv.lock will remain unchanged.

    + +

    Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-binary

    Don’t install pre-built wheels.

    + +

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

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

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

    + +
    --no-build

    Don’t build source distributions.

    + +

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

    + +
    --no-build-isolation

    Disable isolation when building source distributions.

    + +

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

    + +
    --no-build-isolation-package no-build-isolation-package

    Disable isolation when building source distributions for a specific package.

    + +

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

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

    Don’t build source distributions for a specific package

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-dev

    Omit development dependencies.

    + +

    This option is only available when running in a project.

    + +
    --no-index

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --no-project

    Avoid discovering the project or workspace.

    + +

    Instead of searching for projects in the current directory and parent directories, run in an isolated, ephemeral environment populated by the --with requirements.

    + +

    If a virtual environment is active or found in a current or parent directory, it will be used as if there was no project or workspace.

    + +
    --no-sources

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

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --package package

    Run the command in a specific package in the workspace.

    + +

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

    +
    --prerelease prerelease

    The strategy to use when considering pre-release versions.

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

    @@ -160,51 +262,21 @@ uv run [OPTIONS]
  • 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

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

    Disable isolation when building source distributions for a specific package.

    - -

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

    - -
    --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 for the run environment.

    If the interpreter request is satisfied by a discovered environment, the environment will be used.

    See uv python to view supported request formats.

    -
    --cache-dir cache-dir

    Path to the cache directory.

    +
    --python-fetch python-fetch

    Whether to automatically download Python when required

    -

    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.

    +

    Possible values:

    +
      +
    • automatic: Automatically fetch managed Python installations when needed
      • + +
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    --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.

    @@ -220,30 +292,48 @@ uv run [OPTIONS]
  • only-system: Only use system Python installations; never use managed Python installations
    • -
    --python-fetch python-fetch

    Whether to automatically download Python when required

    +
    --quiet, -q

    Do not print any output

    + +
    --refresh

    Refresh all cached data

    + +
    --refresh-package refresh-package

    Refresh cached data for a specific package

    + +
    --reinstall

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

    + +
    --reinstall-package reinstall-package

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

    + +
    --resolution resolution

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

    + +

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

    Possible values:

      -
    • automatic: Automatically fetch managed Python installations when needed
      • +
    • highest: Resolve the highest compatible version of each package
      • -
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    • 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
    -
    --color color-choice

    Control colors in output

    +
    --upgrade, -U

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

    -

    [default: auto]

    -

    Possible values:

    +
    --upgrade-package, -P upgrade-package

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

    -
      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +
    --verbose, -v

    Use verbose output.

    -
  • always: Enables colored output regardless of the detected environment
    • +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    -
  • never: Disables colored output
    • - -
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    +
    --version, -V

    Display the uv version

    -

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

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

    @@ -277,42 +367,10 @@ uv init [OPTIONS] [PATH]

    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.

    - -

    See uv python to view supported request formats.

    - -
    --cache-dir cache-dir

    Path to the cache 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.

    - -

    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]

    @@ -329,6 +387,80 @@ uv init [OPTIONS] [PATH]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --name name

    The name of the project.

    + +

    Defaults to the name of the directory.

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --no-readme

    Do not create a README.md file

    + +
    --no-workspace

    Avoid discovering a workspace.

    + +

    Instead, create a standalone project.

    + +

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

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --python, -p python

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

    + +

    See uv python to view supported request formats.

    + +
    --python-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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    + +
    --virtual

    Create a virtual workspace instead of a project.

    + +

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

    +
    ## uv add @@ -359,17 +491,41 @@ uv add [OPTIONS] ...

    Options

    -
    --optional optional

    Add the requirements to the specified optional dependency group.

    +
    --branch branch

    Branch to use when adding a dependency from Git

    -

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

    +
    --cache-dir cache-dir

    Path to the cache directory.

    -

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

    +

    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.

    -
    --rev rev

    Commit to use when adding a dependency from Git

    +
    --color color-choice

    Control colors in output

    -
    --tag tag

    Tag to use when adding a dependency from Git

    +

    [default: auto]

    +

    Possible values:

    -
    --branch branch

    Branch to use when adding a dependency from Git

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

    Compile Python files to bytecode after installation.

    + +

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

    + +

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

    + +
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    + +

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    + +
    --config-setting, -C config-setting

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

    + +
    --dev

    Add the requirements as development dependencies

    + +
    --exclude-newer exclude-newer

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

    + +

    Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

    --extra extra

    Extras to enable for the dependency.

    @@ -377,12 +533,6 @@ uv add [OPTIONS] ...

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

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

    @@ -395,9 +545,11 @@ uv add [OPTIONS] ...

    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

    +
    --frozen

    Add dependencies without re-locking the project.

    -
    --reinstall-package reinstall-package

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

    +

    The project environment will not be synced.

    + +
    --help, -h

    Display the concise help for this command

    --index-strategy index-strategy

    The strategy to use when resolving against multiple index URLs.

    @@ -412,6 +564,12 @@ uv add [OPTIONS] ...
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • +
    --index-url, -i index-url

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

    + +

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

    + +

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    +
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

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

    @@ -425,19 +583,81 @@ uv add [OPTIONS] ...
  • 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.

    +
    --link-mode link-mode

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

    -

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

    +

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

    Possible values:

      -
    • highest: Resolve the highest compatible version of each package
      • +
    • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
      • -
    • lowest: Resolve the lowest compatible version of each package
      • +
    • copy: Copy packages from the wheel into the site-packages directory
      • -
    • lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
      • +
    • hardlink: Hard link packages from the wheel into the site-packages directory
      • + +
    • symlink: Symbolically link packages from the wheel into the site-packages directory
    +
    --locked

    Assert that the uv.lock will remain unchanged.

    + +

    Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-binary

    Don’t install pre-built wheels.

    + +

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

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

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

    + +
    --no-build

    Don’t build source distributions.

    + +

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

    + +
    --no-build-isolation

    Disable isolation when building source distributions.

    + +

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

    + +
    --no-build-isolation-package no-build-isolation-package

    Disable isolation when building source distributions for a specific package.

    + +

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

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

    Don’t build source distributions for a specific package

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-editable

    Don’t add the requirements as editables

    + +
    --no-index

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --no-sources

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

    + +
    --no-sync

    Avoid syncing the virtual environment after re-locking the project

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --optional optional

    Add the requirements to the specified optional dependency group.

    + +

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

    + +

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

    + +
    --package package

    Add the dependency to a specific package in the workspace

    +
    --prerelease prerelease

    The strategy to use when considering pre-release versions.

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

    @@ -455,47 +675,19 @@ uv add [OPTIONS] ...
  • 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

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

    Disable isolation when building source distributions for a specific package.

    - -

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

    - -
    --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 to use for resolving and syncing.

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

    -
    --cache-dir cache-dir

    Path to the cache directory.

    +
    --python-fetch python-fetch

    Whether to automatically download Python when required

    -

    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.

    +

    Possible values:

    +
      +
    • automatic: Automatically fetch managed Python installations when needed
      • + +
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    --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.

    @@ -511,30 +703,46 @@ uv add [OPTIONS] ...
  • only-system: Only use system Python installations; never use managed Python installations
    • -
    --python-fetch python-fetch

    Whether to automatically download Python when required

    +
    --quiet, -q

    Do not print any output

    + +
    --raw-sources

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

    + +

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

    + +
    --refresh

    Refresh all cached data

    + +
    --refresh-package refresh-package

    Refresh cached data for a specific package

    + +
    --reinstall

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

    + +
    --reinstall-package reinstall-package

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

    + +
    --resolution resolution

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

    + +

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

    Possible values:

      -
    • automatic: Automatically fetch managed Python installations when needed
      • +
    • highest: Resolve the highest compatible version of each package
      • -
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    • 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
    -
    --color color-choice

    Control colors in output

    +
    --rev rev

    Commit to use when adding a dependency from Git

    -

    [default: auto]

    -

    Possible values:

    +
    --tag tag

    Tag to use when adding a dependency from Git

    -
      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +
    --upgrade, -U

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

    -
  • always: Enables colored output regardless of the detected environment
    • +
    --upgrade-package, -P upgrade-package

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

    -
  • never: Disables colored output
    • - -
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    +
    --verbose, -v

    Use verbose output.

    -

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    @@ -566,13 +774,39 @@ uv remove [OPTIONS] ...

    Options

    -
    --optional optional

    Remove the packages from the specified optional dependency group

    +
    --cache-dir cache-dir

    Path to the cache directory.

    -
    --index-url, -i index-url

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

    +

    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.

    -

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

    +
    --color color-choice

    Control colors in output

    -

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    +

    [default: auto]

    +

    Possible values:

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

    Compile Python files to bytecode after installation.

    + +

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

    + +

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

    + +
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    + +

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    + +
    --config-setting, -C config-setting

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

    + +
    --dev

    Remove the packages from the development dependencies

    + +
    --exclude-newer exclude-newer

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

    + +

    Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

    --extra-index-url extra-index-url

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

    @@ -586,9 +820,11 @@ uv remove [OPTIONS] ...

    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

    +
    --frozen

    Remove dependencies without re-locking the project.

    -
    --reinstall-package reinstall-package

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

    +

    The project environment will not be synced.

    + +
    --help, -h

    Display the concise help for this command

    --index-strategy index-strategy

    The strategy to use when resolving against multiple index URLs.

    @@ -603,6 +839,12 @@ uv remove [OPTIONS] ...
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • +
    --index-url, -i index-url

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

    + +

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

    + +

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    +
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

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

    @@ -616,19 +858,75 @@ uv remove [OPTIONS] ...
  • 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.

    +
    --link-mode link-mode

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

    -

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

    +

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

    Possible values:

      -
    • highest: Resolve the highest compatible version of each package
      • +
    • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
      • -
    • lowest: Resolve the lowest compatible version of each package
      • +
    • copy: Copy packages from the wheel into the site-packages directory
      • -
    • lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
      • +
    • hardlink: Hard link packages from the wheel into the site-packages directory
      • + +
    • symlink: Symbolically link packages from the wheel into the site-packages directory
    +
    --locked

    Assert that the uv.lock will remain unchanged.

    + +

    Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-binary

    Don’t install pre-built wheels.

    + +

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

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

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

    + +
    --no-build

    Don’t build source distributions.

    + +

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

    + +
    --no-build-isolation

    Disable isolation when building source distributions.

    + +

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

    + +
    --no-build-isolation-package no-build-isolation-package

    Disable isolation when building source distributions for a specific package.

    + +

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

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

    Don’t build source distributions for a specific package

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-index

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --no-sources

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

    + +
    --no-sync

    Avoid syncing the virtual environment after re-locking the project

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --optional optional

    Remove the packages from the specified optional dependency group

    + +
    --package package

    Remove the dependencies from a specific package in the workspace

    +
    --prerelease prerelease

    The strategy to use when considering pre-release versions.

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

    @@ -646,47 +944,19 @@ uv remove [OPTIONS] ...
  • 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

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

    Disable isolation when building source distributions for a specific package.

    - -

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

    - -
    --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 dependencies from a specific package in the workspace

    -
    --python, -p python

    The Python interpreter to use for resolving and syncing.

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

    -
    --cache-dir cache-dir

    Path to the cache directory.

    +
    --python-fetch python-fetch

    Whether to automatically download Python when required

    -

    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.

    +

    Possible values:

    +
      +
    • automatic: Automatically fetch managed Python installations when needed
      • + +
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    --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.

    @@ -702,30 +972,38 @@ uv remove [OPTIONS] ...
  • only-system: Only use system Python installations; never use managed Python installations
    • -
    --python-fetch python-fetch

    Whether to automatically download Python when required

    +
    --quiet, -q

    Do not print any output

    + +
    --refresh

    Refresh all cached data

    + +
    --refresh-package refresh-package

    Refresh cached data for a specific package

    + +
    --reinstall

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

    + +
    --reinstall-package reinstall-package

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

    + +
    --resolution resolution

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

    + +

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

    Possible values:

      -
    • automatic: Automatically fetch managed Python installations when needed
      • +
    • highest: Resolve the highest compatible version of each package
      • -
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    • 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
    -
    --color color-choice

    Control colors in output

    +
    --upgrade, -U

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

    -

    [default: auto]

    -

    Possible values:

    +
    --upgrade-package, -P upgrade-package

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

    -
      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +
    --verbose, -v

    Use verbose output.

    -
  • always: Enables colored output regardless of the detected environment
    • +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

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

    +
    --version, -V

    Display the uv version

    @@ -741,15 +1019,45 @@ uv sync [OPTIONS]

    Options

    -
    --extra extra

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

    +
    --all-extras

    Include all optional dependencies.

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

    +
    --cache-dir cache-dir

    Path to the cache directory.

    -

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

    +

    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.

    -

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    +
    --color color-choice

    Control colors in output

    + +

    [default: auto]

    +

    Possible values:

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

    Compile Python files to bytecode after installation.

    + +

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

    + +

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

    + +
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    + +

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    + +
    --config-setting, -C config-setting

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

    + +
    --exclude-newer exclude-newer

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

    + +

    Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

    + +
    --extra extra

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

    + +

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

    --extra-index-url extra-index-url

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

    @@ -763,9 +1071,9 @@ uv sync [OPTIONS]

    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

    +
    --frozen

    Install without updating the uv.lock file

    -
    --reinstall-package reinstall-package

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

    +
    --help, -h

    Display the concise help for this command

    --index-strategy index-strategy

    The strategy to use when resolving against multiple index URLs.

    @@ -780,6 +1088,12 @@ uv sync [OPTIONS]
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • +
    --index-url, -i index-url

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

    + +

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

    + +

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    +
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

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

    @@ -793,19 +1107,75 @@ uv sync [OPTIONS]
  • 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.

    +
    --link-mode link-mode

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

    -

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

    +

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

    Possible values:

      -
    • highest: Resolve the highest compatible version of each package
      • +
    • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
      • -
    • lowest: Resolve the lowest compatible version of each package
      • +
    • copy: Copy packages from the wheel into the site-packages directory
      • -
    • lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
      • +
    • hardlink: Hard link packages from the wheel into the site-packages directory
      • + +
    • symlink: Symbolically link packages from the wheel into the site-packages directory
    +
    --locked

    Assert that the uv.lock will remain unchanged

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-binary

    Don’t install pre-built wheels.

    + +

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

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

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

    + +
    --no-build

    Don’t build source distributions.

    + +

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

    + +
    --no-build-isolation

    Disable isolation when building source distributions.

    + +

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

    + +
    --no-build-isolation-package no-build-isolation-package

    Disable isolation when building source distributions for a specific package.

    + +

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

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

    Don’t build source distributions for a specific package

    + +
    --no-cache, -n

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

    + +
    --no-clean

    When syncing, make the minimum necessary changes to satisfy the requirements.

    + +

    By default, uv sync will remove any extraneous packages from the environment, unless --no-build-isolation is enabled.

    + +
    --no-config

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

    + +

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

    + +
    --no-dev

    Omit development dependencies

    + +
    --no-index

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --no-sources

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

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --package package

    Sync a specific package in the workspace

    +
    --prerelease prerelease

    The strategy to use when considering pre-release versions.

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

    @@ -823,39 +1193,6 @@ uv sync [OPTIONS]
  • 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

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

    Disable isolation when building source distributions for a specific package.

    - -

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

    - -
    --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 for the project environment.

    By default, the first interpreter that meets the project’s requires-python constraint is used.

    @@ -864,10 +1201,15 @@ uv sync [OPTIONS]

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

    -
    --cache-dir cache-dir

    Path to the cache directory.

    +
    --python-fetch python-fetch

    Whether to automatically download Python when required

    -

    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.

    +

    Possible values:

    +
      +
    • automatic: Automatically fetch managed Python installations when needed
      • + +
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    --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.

    @@ -883,30 +1225,38 @@ uv sync [OPTIONS]
  • only-system: Only use system Python installations; never use managed Python installations
    • -
    --python-fetch python-fetch

    Whether to automatically download Python when required

    +
    --quiet, -q

    Do not print any output

    + +
    --refresh

    Refresh all cached data

    + +
    --refresh-package refresh-package

    Refresh cached data for a specific package

    + +
    --reinstall

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

    + +
    --reinstall-package reinstall-package

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

    + +
    --resolution resolution

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

    + +

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

    Possible values:

      -
    • automatic: Automatically fetch managed Python installations when needed
      • +
    • highest: Resolve the highest compatible version of each package
      • -
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    • 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
    -
    --color color-choice

    Control colors in output

    +
    --upgrade, -U

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

    -

    [default: auto]

    -

    Possible values:

    +
    --upgrade-package, -P upgrade-package

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

    -
      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +
    --verbose, -v

    Use verbose output.

    -
  • always: Enables colored output regardless of the detected environment
    • +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

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

    +
    --version, -V

    Display the uv version

    @@ -922,151 +1272,10 @@ 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.

    - -

    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

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

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

    Disable isolation when building source distributions for a specific package.

    - -

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

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

    - -

    A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.

    - -

    The interpreter is also used as the fallback value for the minimum Python version if requires-python is not set.

    - -

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

    - -
    --cache-dir cache-dir

    Path to the cache 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.

    - -

    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]

    @@ -1083,36 +1292,11 @@ uv lock [OPTIONS]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    -
    +
    --config-setting, -C config-setting

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

    -## uv tree +
    --exclude-newer exclude-newer

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

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

    +

    Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

    --extra-index-url extra-index-url

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

    @@ -1126,7 +1310,9 @@ uv tree [OPTIONS]

    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

    +
    --frozen

    Assert that a uv.lock exists, without updating it

    + +
    --help, -h

    Display the concise help for this command

    --index-strategy index-strategy

    The strategy to use when resolving against multiple index URLs.

    @@ -1141,6 +1327,12 @@ uv tree [OPTIONS]
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • +
    --index-url, -i index-url

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

    + +

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

    + +

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    +
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

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

    @@ -1154,46 +1346,6 @@ uv tree [OPTIONS]
  • 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

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

    Disable isolation when building source distributions for a specific package.

    - -

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

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

    @@ -1211,12 +1363,328 @@ uv tree [OPTIONS]
  • 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.

    +
    --locked

    Assert that the uv.lock will remain unchanged

    -

    For example, pass --python-version 3.10 to display the dependencies that would be included when installing on Python 3.10.

    +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    -

    Defaults to the version of the discovered Python interpreter.

    +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-binary

    Don’t install pre-built wheels.

    + +

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

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

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

    + +
    --no-build

    Don’t build source distributions.

    + +

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

    + +
    --no-build-isolation

    Disable isolation when building source distributions.

    + +

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

    + +
    --no-build-isolation-package no-build-isolation-package

    Disable isolation when building source distributions for a specific package.

    + +

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

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

    Don’t build source distributions for a specific package

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-index

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --no-sources

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

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --prerelease prerelease

    The strategy to use when considering pre-release versions.

    + +

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

    + +

    Possible values:

    + +
      +
    • disallow: Disallow all pre-release versions
      • + +
    • allow: Allow all pre-release versions
      • + +
    • if-necessary: Allow pre-release versions if all versions of a package are pre-release
      • + +
    • explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
      • + +
    • if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
      • +
    +
    --python, -p python

    The Python interpreter to use during resolution.

    + +

    A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.

    + +

    The interpreter is also used as the fallback value for the minimum Python version if requires-python is not set.

    + +

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

    + +
    --python-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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --refresh

    Refresh all cached data

    + +
    --refresh-package refresh-package

    Refresh cached data for a specific package

    + +
    --resolution resolution

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

    + +

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

    + +

    Possible values:

    + +
      +
    • highest: Resolve the highest compatible version of each package
      • + +
    • lowest: Resolve the lowest compatible version of each package
      • + +
    • lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
      • +
    +
    --upgrade, -U

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

    + +
    --upgrade-package, -P upgrade-package

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

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    + +
    + +## uv tree + +Display the project's dependency tree (experimental) + +

    Usage

    + +``` +uv tree [OPTIONS] +``` + +

    Options

    + +
    --cache-dir cache-dir

    Path to the cache directory.

    + +

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

    + +
    --color color-choice

    Control colors in output

    + +

    [default: auto]

    +

    Possible values:

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

    The path to a uv.toml file to use for configuration.

    + +

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    + +
    --config-setting, -C config-setting

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

    + +
    --depth, -d depth

    Maximum display depth of the dependency tree

    + +

    [default: 255]

    +
    --exclude-newer exclude-newer

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

    + +

    Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

    + +
    --extra-index-url extra-index-url

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

    + +

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

    + +

    All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

    + +
    --find-links, -f find-links

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

    + +

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

    + +

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

    + +
    --frozen

    Display the requirements without locking the project.

    + +

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

    + +
    --help, -h

    Display the concise help for this command

    + +
    --index-strategy index-strategy

    The strategy to use when resolving against multiple index URLs.

    + +

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

    + +

    Possible values:

    + +
      +
    • first-index: Only use results from the first index that returns a match for a given package name
      • + +
    • unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
      • + +
    • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
      • +
    +
    --index-url, -i index-url

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

    + +

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

    + +

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    + +
    --invert

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

    + +
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

    + +

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

    + +

    Defaults to disabled.

    + +

    Possible values:

    + +
      +
    • disabled: Do not use keyring for credential lookup
      • + +
    • subprocess: Use the keyring command for credential lookup
      • +
    +
    --link-mode link-mode

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

    + +

    This option is only used when building source distributions.

    + +

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

    + +

    Possible values:

    + +
      +
    • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
      • + +
    • copy: Copy packages from the wheel into the site-packages directory
      • + +
    • hardlink: Hard link packages from the wheel into the site-packages directory
      • + +
    • symlink: Symbolically link packages from the wheel into the site-packages directory
      • +
    +
    --locked

    Assert that the uv.lock will remain unchanged.

    + +

    Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-binary

    Don’t install pre-built wheels.

    + +

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

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

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

    + +
    --no-build

    Don’t build source distributions.

    + +

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

    + +
    --no-build-isolation

    Disable isolation when building source distributions.

    + +

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

    + +
    --no-build-isolation-package no-build-isolation-package

    Disable isolation when building source distributions for a specific package.

    + +

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

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

    Don’t build source distributions for a specific package

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-dedupe

    Do not de-duplicate repeated dependencies. Usually, when a package has already displayed its dependencies, further occurrences will not re-display its dependencies, and will include a (*) to indicate it has already been shown. This flag will cause those duplicates to be repeated

    + +
    --no-index

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --no-sources

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

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --package package

    Display only the specified packages

    + +
    --prerelease prerelease

    The strategy to use when considering pre-release versions.

    + +

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

    + +

    Possible values:

    + +
      +
    • disallow: Disallow all pre-release versions
      • + +
    • allow: Allow all pre-release versions
      • + +
    • if-necessary: Allow pre-release versions if all versions of a package are pre-release
      • + +
    • explicit: Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
      • + +
    • if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements
      • +
    +
    --prune prune

    Prune the given package from the display of the dependency tree

    + +
    --python, -p python

    The Python interpreter to use for locking and filtering.

    + +

    By default, the tree is filtered to match the platform as reported by the Python interpreter. Use --universal to display the tree for all platforms, or use --python-version or --python-platform to override a subset of markers.

    + +

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

    + +
    --python-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
      • +
    --python-platform python-platform

    The platform to use when filtering the tree.

    For example, pass --platform windows to display the dependencies that would be included when installing on Windows.

    @@ -1258,16 +1726,6 @@ uv tree [OPTIONS]
  • aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
    • -
    --python, -p python

    The Python interpreter to use for locking and filtering.

    - -

    By default, the tree is filtered to match the platform as reported by the Python interpreter. Use --universal to display the tree for all platforms, or use --python-version or --python-platform to override a subset of markers.

    - -

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

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

    @@ -1283,30 +1741,42 @@ uv tree [OPTIONS]
  • only-system: Only use system Python installations; never use managed Python installations
    • -
    --python-fetch python-fetch

    Whether to automatically download Python when required

    +
    --python-version python-version

    The Python version to use when filtering the tree.

    + +

    For example, pass --python-version 3.10 to display the dependencies that would be included when installing on Python 3.10.

    + +

    Defaults to the version of the discovered Python interpreter.

    + +
    --quiet, -q

    Do not print any output

    + +
    --resolution resolution

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

    + +

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

    Possible values:

      -
    • automatic: Automatically fetch managed Python installations when needed
      • +
    • highest: Resolve the highest compatible version of each package
      • -
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    • 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
    -
    --color color-choice

    Control colors in output

    +
    --universal

    Show a platform-independent dependency tree.

    -

    [default: auto]

    -

    Possible values:

    +

    Shows resolved package versions for all Python versions and platforms, rather than filtering to those that are relevant for the current environment.

    -
      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +

      Multiple versions may be shown for a each package.

      -
    • always: Enables colored output regardless of the detected environment
      • +
    --upgrade, -U

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

    -
  • never: Disables colored output
    • - -
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    +
    --upgrade-package, -P upgrade-package

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

    -

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    @@ -1348,19 +1818,37 @@ uv tool run [OPTIONS] [COMMAND]

    Options

    -
    --from from

    Use the given package to provide the command.

    +
    --cache-dir cache-dir

    Path to the cache directory.

    -

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

    +

    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.

    -
    --with with

    Run with the given packages installed

    +
    --color color-choice

    Control colors in output

    -
    --with-requirements with-requirements

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

    +

    [default: auto]

    +

    Possible values:

    -
    --index-url, -i index-url

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

    +
      +
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • -

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

      +
    • always: Enables colored output regardless of the detected environment
      • -

      The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

      +
    • never: Disables colored output
      • +
    +
    --compile-bytecode

    Compile Python files to bytecode after installation.

    + +

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

    + +

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

    + +
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    + +

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    + +
    --config-setting, -C config-setting

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

    + +
    --exclude-newer exclude-newer

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

    + +

    Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

    --extra-index-url extra-index-url

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

    @@ -1374,9 +1862,11 @@ uv tool run [OPTIONS] [COMMAND]

    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

    +
    --from from

    Use the given package to provide the command.

    -
    --reinstall-package reinstall-package

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

    +

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

    + +
    --help, -h

    Display the concise help for this command

    --index-strategy index-strategy

    The strategy to use when resolving against multiple index URLs.

    @@ -1391,6 +1881,14 @@ uv tool run [OPTIONS] [COMMAND]
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • +
    --index-url, -i index-url

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

    + +

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

    + +

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    + +
    --isolated

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

    +
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

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

    @@ -1404,19 +1902,65 @@ uv tool run [OPTIONS] [COMMAND]
  • 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.

    +
    --link-mode link-mode

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

    -

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

    +

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

    Possible values:

      -
    • highest: Resolve the highest compatible version of each package
      • +
    • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
      • -
    • lowest: Resolve the lowest compatible version of each package
      • +
    • copy: Copy packages from the wheel into the site-packages directory
      • -
    • lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
      • +
    • hardlink: Hard link packages from the wheel into the site-packages directory
      • + +
    • symlink: Symbolically link packages from the wheel into the site-packages directory
    +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-binary

    Don’t install pre-built wheels.

    + +

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

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

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

    + +
    --no-build

    Don’t build source distributions.

    + +

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

    + +
    --no-build-isolation

    Disable isolation when building source distributions.

    + +

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

    + +
    --no-build-isolation-package no-build-isolation-package

    Disable isolation when building source distributions for a specific package.

    + +

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

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

    Don’t build source distributions for a specific package

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-index

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --no-sources

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

    + +
    --offline

    Disable network access.

    + +

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

    +
    --prerelease prerelease

    The strategy to use when considering pre-release versions.

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

    @@ -1434,45 +1978,19 @@ uv tool run [OPTIONS] [COMMAND]
  • 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

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

    Disable isolation when building source distributions for a specific package.

    - -

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

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

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

    -
    --cache-dir cache-dir

    Path to the cache directory.

    +
    --python-fetch python-fetch

    Whether to automatically download Python when required

    -

    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.

    +

    Possible values:

    +
      +
    • automatic: Automatically fetch managed Python installations when needed
      • + +
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    --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.

    @@ -1488,30 +2006,42 @@ uv tool run [OPTIONS] [COMMAND]
  • only-system: Only use system Python installations; never use managed Python installations
    • -
    --python-fetch python-fetch

    Whether to automatically download Python when required

    +
    --quiet, -q

    Do not print any output

    + +
    --refresh

    Refresh all cached data

    + +
    --refresh-package refresh-package

    Refresh cached data for a specific package

    + +
    --reinstall

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

    + +
    --reinstall-package reinstall-package

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

    + +
    --resolution resolution

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

    + +

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

    Possible values:

      -
    • automatic: Automatically fetch managed Python installations when needed
      • +
    • highest: Resolve the highest compatible version of each package
      • -
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    • 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
    -
    --color color-choice

    Control colors in output

    +
    --upgrade, -U

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

    -

    [default: auto]

    -

    Possible values:

    +
    --upgrade-package, -P upgrade-package

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

    -
      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +
    --verbose, -v

    Use verbose output.

    -
  • always: Enables colored output regardless of the detected environment
    • +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    -
  • never: Disables colored output
    • - -
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    +
    --version, -V

    Display the uv version

    -

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --with with

    Run with the given packages installed

    + +
    --with-requirements with-requirements

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

    @@ -1533,15 +2063,37 @@ uv tool install [OPTIONS]

    Options

    -
    --with with

    Include the following extra requirements

    +
    --cache-dir cache-dir

    Path to the cache directory.

    -
    --with-requirements with-requirements

    Run all requirements listed in the given requirements.txt files

    +

    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.

    -
    --index-url, -i index-url

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

    +
    --color color-choice

    Control colors in output

    -

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

    +

    [default: auto]

    +

    Possible values:

    -

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

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

    Compile Python files to bytecode after installation.

    + +

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

    + +

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

    + +
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    + +

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    + +
    --config-setting, -C config-setting

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

    + +
    --editable, -e
    --exclude-newer exclude-newer

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

    + +

    Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

    --extra-index-url extra-index-url

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

    @@ -1555,9 +2107,11 @@ uv tool install [OPTIONS]

    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

    +
    --force

    Force installation of the tool.

    -
    --reinstall-package reinstall-package

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

    +

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

    + +
    --help, -h

    Display the concise help for this command

    --index-strategy index-strategy

    The strategy to use when resolving against multiple index URLs.

    @@ -1572,6 +2126,12 @@ uv tool install [OPTIONS]
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • +
    --index-url, -i index-url

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

    + +

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

    + +

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    +
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

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

    @@ -1585,19 +2145,65 @@ uv tool install [OPTIONS]
  • 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.

    +
    --link-mode link-mode

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

    -

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

    +

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

    Possible values:

      -
    • highest: Resolve the highest compatible version of each package
      • +
    • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
      • -
    • lowest: Resolve the lowest compatible version of each package
      • +
    • copy: Copy packages from the wheel into the site-packages directory
      • -
    • lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
      • +
    • hardlink: Hard link packages from the wheel into the site-packages directory
      • + +
    • symlink: Symbolically link packages from the wheel into the site-packages directory
    +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-binary

    Don’t install pre-built wheels.

    + +

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

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

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

    + +
    --no-build

    Don’t build source distributions.

    + +

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

    + +
    --no-build-isolation

    Disable isolation when building source distributions.

    + +

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

    + +
    --no-build-isolation-package no-build-isolation-package

    Disable isolation when building source distributions for a specific package.

    + +

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

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

    Don’t build source distributions for a specific package

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-index

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --no-sources

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

    + +
    --offline

    Disable network access.

    + +

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

    +
    --prerelease prerelease

    The strategy to use when considering pre-release versions.

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

    @@ -1615,45 +2221,19 @@ uv tool install [OPTIONS]
  • 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

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

    Disable isolation when building source distributions for a specific package.

    - -

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

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

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

    -
    --cache-dir cache-dir

    Path to the cache directory.

    +
    --python-fetch python-fetch

    Whether to automatically download Python when required

    -

    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.

    +

    Possible values:

    +
      +
    • automatic: Automatically fetch managed Python installations when needed
      • + +
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    --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.

    @@ -1669,30 +2249,42 @@ uv tool install [OPTIONS]
  • only-system: Only use system Python installations; never use managed Python installations
    • -
    --python-fetch python-fetch

    Whether to automatically download Python when required

    +
    --quiet, -q

    Do not print any output

    + +
    --refresh

    Refresh all cached data

    + +
    --refresh-package refresh-package

    Refresh cached data for a specific package

    + +
    --reinstall

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

    + +
    --reinstall-package reinstall-package

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

    + +
    --resolution resolution

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

    + +

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

    Possible values:

      -
    • automatic: Automatically fetch managed Python installations when needed
      • +
    • highest: Resolve the highest compatible version of each package
      • -
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    • 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
    -
    --color color-choice

    Control colors in output

    +
    --upgrade, -U

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

    -

    [default: auto]

    -

    Possible values:

    +
    --upgrade-package, -P upgrade-package

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

    -
      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +
    --verbose, -v

    Use verbose output.

    -
  • always: Enables colored output regardless of the detected environment
    • +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    -
  • never: Disables colored output
    • - -
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    +
    --version, -V

    Display the uv version

    -

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --with with

    Include the following extra requirements

    + +
    --with-requirements with-requirements

    Run all requirements listed in the given requirements.txt files

    @@ -1712,30 +2304,6 @@ uv tool list [OPTIONS]

    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]

    @@ -1752,6 +2320,62 @@ uv tool list [OPTIONS]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --show-paths

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

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv tool uninstall @@ -1772,34 +2396,12 @@ uv tool uninstall [OPTIONS]

    Options

    -
    --cache-dir cache-dir

    Path to the cache directory.

    +
    --all

    Uninstall all tools

    + +
    --cache-dir cache-dir

    Path to the cache directory.

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

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

    @@ -1816,6 +2418,60 @@ uv tool uninstall [OPTIONS]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv tool update-shell @@ -1834,30 +2490,6 @@ uv tool update-shell [OPTIONS]

    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]

    @@ -1874,6 +2506,60 @@ uv tool update-shell [OPTIONS]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv tool dir @@ -1888,34 +2574,14 @@ uv tool dir [OPTIONS]

    Options

    -
    --cache-dir cache-dir

    Path to the cache directory.

    +
    --bin

    Show the directory into which uv tool will install executables.

    + +

    By default, uv tool dir shows the directory into which the tool Python environments themselves are installed, rather than the directory containing the linked executables.

    + +
    --cache-dir cache-dir

    Path to the cache directory.

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

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

    @@ -1932,6 +2598,60 @@ uv tool dir [OPTIONS]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ## uv python @@ -2011,34 +2731,14 @@ uv python list [OPTIONS]

    Options

    -
    --cache-dir cache-dir

    Path to the cache directory.

    +
    --all-platforms

    List Python installations for all platforms

    + +
    --all-versions

    List all Python versions, including outdated patch versions

    + +
    --cache-dir cache-dir

    Path to the cache directory.

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

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

    @@ -2055,6 +2755,62 @@ uv python list [OPTIONS]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --only-installed

    Only show installed Python versions, exclude available downloads

    + +
    --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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv python install @@ -2083,30 +2839,6 @@ uv python install [OPTIONS] [TARGETS]...

    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]

    @@ -2123,6 +2855,62 @@ uv python install [OPTIONS] [TARGETS]...

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --reinstall, -r

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

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv python find @@ -2149,30 +2937,6 @@ uv python find [OPTIONS] [REQUEST]

    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]

    @@ -2189,6 +2953,60 @@ uv python find [OPTIONS] [REQUEST]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv python pin @@ -2217,30 +3035,6 @@ uv python pin [OPTIONS] [REQUEST]

    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]

    @@ -2257,6 +3051,66 @@ uv python pin [OPTIONS] [REQUEST]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --no-workspace

    Avoid validating the Python pin against the workspace in the current directory or any parent directory

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --python-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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --resolved

    Write the resolved Python interpreter path instead of the request.

    + +

    Ensures that the exact same interpreter is used.

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv python dir @@ -2275,30 +3129,6 @@ uv python dir [OPTIONS]

    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]

    @@ -2315,6 +3145,60 @@ uv python dir [OPTIONS]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv python uninstall @@ -2337,34 +3221,12 @@ uv python uninstall [OPTIONS] ...

    Options

    -
    --cache-dir cache-dir

    Path to the cache directory.

    +
    --all

    Uninstall all managed Python versions

    + +
    --cache-dir cache-dir

    Path to the cache directory.

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

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

    @@ -2381,6 +3243,60 @@ uv python uninstall [OPTIONS] ...

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ## uv pip @@ -2437,32 +3353,73 @@ uv pip compile [OPTIONS] ...

    Options

    -
    --constraint, -c constraint

    Constrain versions using the given requirements files.

    +
    --all-extras

    Include all optional dependencies.

    + +

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

    + +
    --annotation-style annotation-style

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

    + +

    Defaults to split.

    + +

    Possible values:

    + +
      +
    • line: Render the annotations on a single, comma-separated line
      • + +
    • split: Render each annotation on its own line
      • +
    +
    --build-constraint, -b build-constraint

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

    + +

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

    + +
    --cache-dir cache-dir

    Path to the cache directory.

    + +

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

    + +
    --color color-choice

    Control colors in output

    + +

    [default: auto]

    +

    Possible values:

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

    The path to a uv.toml file to use for configuration.

    + +

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    + +
    --config-setting, -C config-setting

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

    + +
    --constraint, -c constraint

    Constrain versions using the given requirements files.

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

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

    -
    --override override

    Override versions using the given requirements files.

    +
    --custom-compile-command custom-compile-command

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

    -

    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.

    +

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

    -

    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.

    +
    --emit-build-options

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

    -
    --build-constraint, -b build-constraint

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

    +
    --emit-find-links

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

    -

    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.

    +
    --emit-index-annotation

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

    + +
    --emit-index-url

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

    + +
    --exclude-newer exclude-newer

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

    + +

    Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

    --extra extra

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

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

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

    @@ -2475,7 +3432,9 @@ uv pip compile [OPTIONS] ...

    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

    +
    --generate-hashes

    Include distribution hashes in the output file

    + +
    --help, -h

    Display the concise help for this command

    --index-strategy index-strategy

    The strategy to use when resolving against multiple index URLs.

    @@ -2490,6 +3449,12 @@ uv pip compile [OPTIONS] ...
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • +
    --index-url, -i index-url

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

    + +

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

    + +

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    +
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

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

    @@ -2503,45 +3468,7 @@ uv pip compile [OPTIONS] ...
  • 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

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

    Disable isolation when building source distributions for a specific package.

    - -

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

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

    +
    --legacy-setup-py

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

    --link-mode link-mode

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

    @@ -2560,27 +3487,95 @@ uv pip compile [OPTIONS] ...
  • symlink: Symbolically link packages from the wheel into the site-packages directory
    • -
    --refresh-package refresh-package

    Refresh cached data for a specific package

    +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-annotate

    Exclude comment annotations indicating the source of each package

    + +
    --no-binary no-binary

    Don’t install pre-built wheels.

    + +

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

    + +

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

    + +
    --no-build

    Don’t build source distributions.

    + +

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

    + +

    Alias for --only-binary :all:.

    + +
    --no-build-isolation

    Disable isolation when building source distributions.

    + +

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

    + +
    --no-build-isolation-package no-build-isolation-package

    Disable isolation when building source distributions for a specific package.

    + +

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

    + +
    --no-cache, -n

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

    + +
    --no-deps

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

    + +
    --no-emit-package no-emit-package

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

    + +
    --no-header

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

    + +
    --no-index

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --no-sources

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

    + +
    --no-strip-extras

    Include extras in the output file.

    + +

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

    + +
    --no-strip-markers

    Include environment markers in the output file.

    + +

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

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --only-binary only-binary

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

    + +

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

    + +

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

    --output-file, -o output-file

    Write the compiled requirements to the given requirements.txt file.

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

    -
    --annotation-style annotation-style

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

    +
    --override override

    Override versions using the given requirements files.

    -

    Defaults to split.

    +

    Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.

    + +

    While constraints are additive, in that they’re combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.

    + +
    --prerelease prerelease

    The strategy to use when considering pre-release versions.

    + +

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

    Possible values:

      -
    • line: Render the annotations on a single, comma-separated line
      • +
    • disallow: Disallow all pre-release versions
      • -
    • split: Render each annotation on its own line
      • +
    • 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
    -
    --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 to use during resolution.

    A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.

    @@ -2589,28 +3584,15 @@ uv pip compile [OPTIONS] ...

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

    -
    --no-binary no-binary

    Don’t install pre-built wheels.

    +
    --python-fetch python-fetch

    Whether to automatically download Python when required

    -

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

    +

    Possible values:

    -

    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 Python version to use for resolution.

    - -

    For example, 3.8 or 3.8.17.

    - -

    Defaults to the version of the Python interpreter used for resolution.

    - -

    Defines the minimum Python version that must be supported by the resolved requirements.

    - -

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

    +
      +
    • automatic: Automatically fetch managed Python installations when needed
      • +
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    --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.

    @@ -2650,12 +3632,6 @@ uv pip compile [OPTIONS] ...
  • 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.

    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.

    @@ -2671,30 +3647,54 @@ uv pip compile [OPTIONS] ...
  • only-system: Only use system Python installations; never use managed Python installations
    • -
    --python-fetch python-fetch

    Whether to automatically download Python when required

    +
    --python-version, -p python-version

    The Python version to use for resolution.

    + +

    For example, 3.8 or 3.8.17.

    + +

    Defaults to the version of the Python interpreter used for resolution.

    + +

    Defines the minimum Python version that must be supported by the resolved requirements.

    + +

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

    + +
    --quiet, -q

    Do not print any output

    + +
    --refresh

    Refresh all cached data

    + +
    --refresh-package refresh-package

    Refresh cached data for a specific package

    + +
    --resolution resolution

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

    + +

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

    Possible values:

      -
    • automatic: Automatically fetch managed Python installations when needed
      • +
    • highest: Resolve the highest compatible version of each package
      • -
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    • 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
    -
    --color color-choice

    Control colors in output

    +
    --system

    Install packages into the system Python environment.

    -

    [default: auto]

    -

    Possible values:

    +

    By default, uv uses the virtual environment in the current working directory or any parent directory, falling back to searching for a Python executable in PATH. The --system option instructs uv to avoid using a virtual environment Python and restrict its search to the system path.

    -
      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +
    --universal

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

    -
  • always: Enables colored output regardless of the detected environment
    • +

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

    -
  • never: Disables colored output
    • - -
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    +

    Implies --no-strip-markers.

    -

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --upgrade, -U

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

    + +
    --upgrade-package, -P upgrade-package

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

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    @@ -2720,21 +3720,55 @@ uv pip sync [OPTIONS] ...

    Options

    -
    --constraint, -c constraint

    Constrain versions using the given requirements files.

    +
    --allow-empty-requirements

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

    -

    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.

    +
    --break-system-packages

    Allow uv to modify an EXTERNALLY-MANAGED Python installation.

    -

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

    +

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

    --build-constraint, -b build-constraint

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

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

    -
    --index-url, -i index-url

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

    +
    --cache-dir cache-dir

    Path to the cache directory.

    -

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

    +

    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.

    -

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    +
    --color color-choice

    Control colors in output

    + +

    [default: auto]

    +

    Possible values:

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

    Compile Python files to bytecode after installation.

    + +

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

    + +

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

    + +
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    + +

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    + +
    --config-setting, -C config-setting

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

    + +
    --constraint, -c constraint

    Constrain versions using the given requirements files.

    + +

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

    + +

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

    + +
    --dry-run

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

    + +
    --exclude-newer exclude-newer

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

    + +

    Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

    --extra-index-url extra-index-url

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

    @@ -2748,7 +3782,7 @@ uv pip sync [OPTIONS] ...

    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

    +
    --help, -h

    Display the concise help for this command

    --index-strategy index-strategy

    The strategy to use when resolving against multiple index URLs.

    @@ -2763,6 +3797,12 @@ uv pip sync [OPTIONS] ...
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • +
    --index-url, -i index-url

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

    + +

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

    + +

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    +
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

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

    @@ -2776,11 +3816,7 @@ uv pip sync [OPTIONS] ...
  • 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).

    +
    --legacy-setup-py

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

    --link-mode link-mode

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

    @@ -2797,36 +3833,67 @@ uv pip sync [OPTIONS] ...
  • symlink: Symbolically link packages from the wheel into the site-packages directory
    • -
    --refresh-package refresh-package

    Refresh cached data for a specific package

    +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    -
    --python, -p python

    The Python interpreter into which packages should be installed.

    +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    -

    By default, syncing requires a virtual environment. An path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

    +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    -

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

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

    +
    --no-allow-empty-requirements
    --no-binary no-binary

    Don’t install pre-built wheels.

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

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

    +
    --no-break-system-packages
    --no-build

    Don’t build source distributions.

    + +

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

    + +

    Alias for --only-binary :all:.

    + +
    --no-build-isolation

    Disable isolation when building source distributions.

    + +

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

    + +
    --no-cache, -n

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

    + +
    --no-index

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --no-sources

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

    + +
    --offline

    Disable network access.

    + +

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

    +
    --only-binary only-binary

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

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

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

    -
    --python-version python-version

    The minimum Python version that should be supported by the requirements (e.g., 3.7 or 3.7.9).

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

    -

    If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.

    +

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

    +
    --python, -p python

    The Python interpreter into which packages should be installed.

    + +

    By default, syncing requires a virtual environment. An path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

    + +

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

    + +
    --python-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
      • +
    --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.

    @@ -2868,10 +3935,6 @@ uv pip sync [OPTIONS] ...
  • 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.

    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.

    @@ -2887,30 +3950,49 @@ uv pip sync [OPTIONS] ...
  • only-system: Only use system Python installations; never use managed Python installations
    • -
    --python-fetch python-fetch

    Whether to automatically download Python when required

    +
    --python-version python-version

    The minimum Python version that should be supported by the requirements (e.g., 3.7 or 3.7.9).

    -

    Possible values:

    +

    If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.

    + +
    --quiet, -q

    Do not print any output

    + +
    --refresh

    Refresh all cached data

    + +
    --refresh-package refresh-package

    Refresh cached data for a specific package

    + +
    --reinstall

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

    + +
    --reinstall-package reinstall-package

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

    + +
    --require-hashes

    Require a matching hash for each requirement.

    + +

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

    + +

    Hash-checking mode introduces a number of additional constraints:

      -
    • automatic: Automatically fetch managed Python installations when needed
      • - -
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    • Git dependencies are not supported. - Editable installs are not supported. - Local dependencies are not supported, unless they point to a specific wheel (.whl) or source archive (.zip, .tar.gz), as opposed to a directory.
    -
    --color color-choice

    Control colors in output

    -

    [default: auto]

    -

    Possible values:

    +
    --strict

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

    -
      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +
    --system

    Install packages into the system Python environment.

    -
  • always: Enables colored output regardless of the detected environment
    • +

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

    -
  • never: Disables colored output
    • - -
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    +

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

    -

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --target target

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

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --verify-hashes

    Validate any hashes provided in the requirements file.

    + +

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

    + +
    --version, -V

    Display the uv version

    @@ -2932,13 +4014,45 @@ uv pip install [OPTIONS] |--editable Options -
    --requirement, -r requirement

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

    +
    --all-extras

    Include all optional dependencies.

    -

    If a pyproject.toml, setup.py, or setup.cfg file is provided, uv will extract the requirements for the relevant project.

    +

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

    -

    If - is provided, then requirements will be read from stdin.

    +
    --break-system-packages

    Allow uv to modify an EXTERNALLY-MANAGED Python installation.

    -
    --editable, -e editable

    Install the editable package based on the provided local file path

    +

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

    + +
    --build-constraint, -b build-constraint

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

    + +

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

    + +
    --cache-dir cache-dir

    Path to the cache directory.

    + +

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

    + +
    --color color-choice

    Control colors in output

    + +

    [default: auto]

    +

    Possible values:

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

    Compile Python files to bytecode after installation.

    + +

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

    + +

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

    + +
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    + +

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    + +
    --config-setting, -C config-setting

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

    --constraint, -c constraint

    Constrain versions using the given requirements files.

    @@ -2946,26 +4060,18 @@ uv pip install [OPTIONS] |--editable This is equivalent to pip’s --constraint option.

    -
    --override override

    Override versions using the given requirements files.

    +
    --dry-run

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

    -

    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.

    +
    --editable, -e editable

    Install the editable package based on the provided local file path

    -

    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.

    +
    --exclude-newer exclude-newer

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

    -
    --build-constraint, -b build-constraint

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

    - -

    Constraints files are requirements.txt-like files that only control the version of a requirement that’s installed. However, including a package in a constraints file will not trigger the installation of that package.

    +

    Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

    --extra extra

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

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

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

    @@ -2978,9 +4084,7 @@ uv pip install [OPTIONS] |--editable 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

    +
    --help, -h

    Display the concise help for this command

    --index-strategy index-strategy

    The strategy to use when resolving against multiple index URLs.

    @@ -2995,6 +4099,12 @@ uv pip install [OPTIONS] |--editable unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index +
    --index-url, -i index-url

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

    + +

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

    + +

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    +
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

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

    @@ -3008,19 +4118,85 @@ uv pip install [OPTIONS] |--editable 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.

    +
    --legacy-setup-py

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

    -

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

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

      -
    • highest: Resolve the highest compatible version of each package
      • +
    • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
      • -
    • lowest: Resolve the lowest compatible version of each package
      • +
    • copy: Copy packages from the wheel into the site-packages directory
      • -
    • lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
      • +
    • hardlink: Hard link packages from the wheel into the site-packages directory
      • + +
    • symlink: Symbolically link packages from the wheel into the site-packages directory
    +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-binary no-binary

    Don’t install pre-built wheels.

    + +

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

    + +

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

    + +
    --no-break-system-packages
    --no-build

    Don’t build source distributions.

    + +

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

    + +

    Alias for --only-binary :all:.

    + +
    --no-build-isolation

    Disable isolation when building source distributions.

    + +

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

    + +
    --no-build-isolation-package no-build-isolation-package

    Disable isolation when building source distributions for a specific package.

    + +

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

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-deps

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

    + +
    --no-index

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --no-sources

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

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --only-binary only-binary

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

    + +

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

    + +

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

    + +
    --override override

    Override versions using the given requirements files.

    + +

    Overrides files are requirements.txt-like files that force a specific version of a requirement to be installed, regardless of the requirements declared by any constituent package, and regardless of whether this would be considered an invalid resolution.

    + +

    While constraints are additive, in that they’re combined with the requirements of the constituent packages, overrides are absolute, in that they completely replace the requirements of the constituent packages.

    + +
    --prefix prefix

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

    + +

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

    +
    --prerelease prerelease

    The strategy to use when considering pre-release versions.

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

    @@ -3038,61 +4214,21 @@ uv pip install [OPTIONS] |--editable 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

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

    Disable isolation when building source distributions for a specific package.

    - -

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

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

    By default, installation requires a virtual environment. An path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

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

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

    +
    --python-fetch python-fetch

    Whether to automatically download Python when required

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

    +

    Possible values:

    -

    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.

    - -

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

    +
      +
    • automatic: Automatically fetch managed Python installations when needed
      • +
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    --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.

    @@ -3134,10 +4270,6 @@ uv pip install [OPTIONS] |--editable 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.

    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.

    @@ -3153,30 +4285,72 @@ uv pip install [OPTIONS] |--editable only-system: Only use system Python installations; never use managed Python installations -
    --python-fetch python-fetch

    Whether to automatically download Python when required

    +
    --python-version python-version

    The minimum Python version that should be supported by the requirements (e.g., 3.7 or 3.7.9).

    + +

    If a patch version is omitted, the minimum patch version is assumed. For example, 3.7 is mapped to 3.7.0.

    + +
    --quiet, -q

    Do not print any output

    + +
    --refresh

    Refresh all cached data

    + +
    --refresh-package refresh-package

    Refresh cached data for a specific package

    + +
    --reinstall

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

    + +
    --reinstall-package reinstall-package

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

    + +
    --require-hashes

    Require a matching hash for each requirement.

    + +

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

    + +

    Hash-checking mode introduces a number of additional constraints:

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

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

    + +

    If a pyproject.toml, setup.py, or setup.cfg file is provided, uv will extract the requirements for the relevant project.

    + +

    If - is provided, then requirements will be read from stdin.

    + +
    --resolution resolution

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

    + +

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

    Possible values:

      -
    • automatic: Automatically fetch managed Python installations when needed
      • +
    • highest: Resolve the highest compatible version of each package
      • -
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • +
    • 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
    -
    --color color-choice

    Control colors in output

    +
    --strict

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

    -

    [default: auto]

    -

    Possible values:

    +
    --system

    Install packages into the system Python environment.

    -
      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +

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

      -
    • always: Enables colored output regardless of the detected environment
      • +

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

      -
    • never: Disables colored output
      • -
    -
    --config-file config-file

    The path to a uv.toml file to use for configuration.

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

    -

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --upgrade, -U

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

    + +
    --upgrade-package, -P upgrade-package

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

    + +
    --user
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --verify-hashes

    Validate any hashes provided in the requirements file.

    + +

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

    + +
    --version, -V

    Display the uv version

    @@ -3198,59 +4372,14 @@ uv pip uninstall [OPTIONS] >

    Options

    -
    --requirement, -r requirement

    Uninstall all packages listed in the given requirements files

    +
    --break-system-packages

    Allow uv to modify an EXTERNALLY-MANAGED Python installation.

    -
    --python, -p python

    The Python interpreter from which packages should be uninstalled.

    - -

    By default, uninstallation requires a virtual environment. An path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

    - -

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

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

    +

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

    --cache-dir cache-dir

    Path to the cache directory.

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

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

    @@ -3267,6 +4396,91 @@ uv pip uninstall [OPTIONS] >

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for remote requirements files.

    + +

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

    + +

    Defaults to disabled.

    + +

    Possible values:

    + +
      +
    • disabled: Do not use keyring for credential lookup
      • + +
    • subprocess: Use the keyring command for credential lookup
      • +
    +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-break-system-packages
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --prefix prefix

    Uninstall packages from the specified --prefix directory

    + +
    --python, -p python

    The Python interpreter from which packages should be uninstalled.

    + +

    By default, uninstallation requires a virtual environment. An path to an alternative Python can be provided, but it is only recommended in continuous integration (CI) environments and should be used with caution, as it can modify the system Python installation.

    + +

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

    + +
    --python-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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --requirement, -r requirement

    Uninstall all packages listed in the given requirements files

    + +
    --system

    Use the system Python to uninstall packages.

    + +

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

    + +

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

    + +
    --target target

    Uninstall packages from the specified --target directory

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv pip freeze @@ -3281,40 +4495,10 @@ uv pip freeze [OPTIONS]

    Options

    -
    --python, -p python

    The Python interpreter for which packages should be listed.

    - -

    By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.

    - -

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

    - -
    --cache-dir cache-dir

    Path to the cache 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.

    - -

    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]

    @@ -3331,6 +4515,76 @@ uv pip freeze [OPTIONS]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --exclude-editable

    Exclude any editable packages from output

    + +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --python, -p python

    The Python interpreter for which packages should be listed.

    + +

    By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.

    + +

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

    + +
    --python-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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --strict

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

    + +
    --system

    List packages in the system Python environment.

    + +

    Disables discovery of virtual environments.

    + +

    See uv python for details on Python discovery.

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv pip list @@ -3345,54 +4599,10 @@ 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.

    - -

    By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.

    - -

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

    - -
    --cache-dir cache-dir

    Path to the cache 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.

    - -

    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]

    @@ -3409,6 +4619,92 @@ uv pip list [OPTIONS]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --editable, -e

    Only include editable projects

    + +
    --exclude exclude

    Exclude the specified package(s) from the output

    + +
    --exclude-editable

    Exclude any editable packages from output

    + +
    --format format

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

    + +

    [default: columns]

    +

    Possible values:

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

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --python, -p python

    The Python interpreter for which packages should be listed.

    + +

    By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.

    + +

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

    + +
    --python-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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --strict

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

    + +
    --system

    List packages in the system Python environment.

    + +

    Disables discovery of virtual environments.

    + +

    See uv python for details on Python discovery.

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv pip show @@ -3429,40 +4725,10 @@ uv pip show [OPTIONS] [PACKAGE]...

    Options

    -
    --python, -p python

    The Python interpreter to find the package in.

    - -

    By default, uv looks for packages in a virtual environment but will look for packages in a system Python environment if no virtual environment is found.

    - -

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

    - -
    --cache-dir cache-dir

    Path to the cache 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.

    - -

    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]

    @@ -3479,6 +4745,74 @@ uv pip show [OPTIONS] [PACKAGE]...

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --python, -p python

    The Python interpreter to find the package in.

    + +

    By default, uv looks for packages in a virtual environment but will look for packages in a system Python environment if no virtual environment is found.

    + +

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

    + +
    --python-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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --strict

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

    + +
    --system

    Show a package in the system Python environment.

    + +

    Disables discovery of virtual environments.

    + +

    See uv python for details on Python discovery.

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv pip tree @@ -3493,47 +4827,10 @@ 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.

    - -

    By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.

    - -

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

    - -
    --cache-dir cache-dir

    Path to the cache 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.

    - -

    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]

    @@ -3550,6 +4847,87 @@ uv pip tree [OPTIONS]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --depth, -d depth

    Maximum display depth of the dependency tree

    + +

    [default: 255]

    +
    --help, -h

    Display the concise help for this command

    + +
    --invert

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

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-dedupe

    Do not de-duplicate repeated dependencies. Usually, when a package has already displayed its dependencies, further occurrences will not re-display its dependencies, and will include a (*) to indicate it has already been shown. This flag will cause those duplicates to be repeated

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --no-system
    --offline

    Disable network access.

    + +

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

    + +
    --package package

    Display only the specified packages

    + +
    --prune prune

    Prune the given package from the display of the dependency tree

    + +
    --python, -p python

    The Python interpreter for which packages should be listed.

    + +

    By default, uv lists packages in a virtual environment but will show packages in a system Python environment if no virtual environment is found.

    + +

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

    + +
    --python-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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --show-version-specifiers

    Show the version constraint(s) imposed on each package

    + +
    --strict

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

    + +
    --system

    List packages in the system Python environment.

    + +

    Disables discovery of virtual environments.

    + +

    See uv python for details on Python discovery.

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv pip check @@ -3564,40 +4942,10 @@ uv pip check [OPTIONS]

    Options

    -
    --python, -p python

    The Python interpreter for which packages should be checked.

    - -

    By default, uv checks packages in a virtual environment but will check packages in a system Python environment if no virtual environment is found.

    - -

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

    - -
    --cache-dir cache-dir

    Path to the cache 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.

    - -

    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]

    @@ -3614,6 +4962,72 @@ uv pip check [OPTIONS]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --python, -p python

    The Python interpreter for which packages should be checked.

    + +

    By default, uv checks packages in a virtual environment but will check packages in a system Python environment if no virtual environment is found.

    + +

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

    + +
    --python-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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --system

    Check packages in the system Python environment.

    + +

    Disables discovery of virtual environments.

    + +

    See uv python for details on Python discovery.

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ## uv venv @@ -3634,11 +5048,120 @@ uv venv [OPTIONS] [NAME]

    Options

    -
    --python, -p python

    The Python interpreter to use for the virtual environment.

    +
    --allow-existing

    Preserve any existing files or directories at the target path.

    -

    During virtual environment creation, uv will not look for Python interpreters in virtual environments.

    +

    By default, uv venv will remove an existing virtual environment at the given path, and exit with an error if the path is non-empty but not a virtual environment. The --allow-existing option will instead write to the given path, regardless of its contents, and without clearing it beforehand.

    -

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

    +

    WARNING: This option can lead to unexpected behavior if the existing virtual environment and the newly-created virtual environment are linked to different Python interpreters.

    + +
    --cache-dir cache-dir

    Path to the cache directory.

    + +

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

    + +
    --color color-choice

    Control colors in output

    + +

    [default: auto]

    +

    Possible values:

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

    The path to a uv.toml file to use for configuration.

    + +

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    + +
    --exclude-newer exclude-newer

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

    + +

    Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and UTC dates in the same format (e.g., 2006-12-02).

    + +
    --extra-index-url extra-index-url

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

    + +

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

    + +

    All indexes provided via this flag take priority over the index specified by --index-url (which defaults to PyPI). When multiple --extra-index-url flags are provided, earlier values take priority.

    + +
    --find-links, -f find-links

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

    + +

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

    + +

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

    + +
    --help, -h

    Display the concise help for this command

    + +
    --index-strategy index-strategy

    The strategy to use when resolving against multiple index URLs.

    + +

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

    + +

    Possible values:

    + +
      +
    • first-index: Only use results from the first index that returns a match for a given package name
      • + +
    • unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
      • + +
    • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
      • +
    +
    --index-url, -i index-url

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

    + +

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

    + +

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    + +
    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

    + +

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

    + +

    Defaults to disabled.

    + +

    Possible values:

    + +
      +
    • disabled: Do not use keyring for credential lookup
      • + +
    • subprocess: Use the keyring command for credential lookup
      • +
    +
    --link-mode link-mode

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

    + +

    This option is only used for installing seed packages.

    + +

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

    + +

    Possible values:

    + +
      +
    • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages directory
      • + +
    • copy: Copy packages from the wheel into the site-packages directory
      • + +
    • hardlink: Hard link packages from the wheel into the site-packages directory
      • + +
    • symlink: Symbolically link packages from the wheel into the site-packages directory
      • +
    +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-index

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    --prompt prompt

    Provide an alternative prompt prefix for the virtual environment.

    @@ -3658,75 +5181,21 @@ uv venv [OPTIONS] [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>).

    +
    --python, -p python

    The Python interpreter to use for the virtual environment.

    -

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

    +

    During virtual environment creation, uv will not look for Python interpreters in virtual environments.

    -

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    +

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

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

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

    +
    --python-fetch python-fetch

    Whether to automatically download Python when required

    Possible values:

      -
    • first-index: Only use results from the first index that returns a match for a given package name
      • +
    • automatic: Automatically fetch managed Python installations when needed
      • -
    • 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
      • +
    • manual: Do not automatically fetch managed Python installations; require explicit installation
    -
    --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.

    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.

    @@ -3742,30 +5211,29 @@ uv venv [OPTIONS] [NAME]
  • only-system: Only use system Python installations; never use managed Python installations
    • -
    --python-fetch python-fetch

    Whether to automatically download Python when required

    +
    --quiet, -q

    Do not print any output

    -

    Possible values:

    +
    --relocatable

    Make the virtual environment relocatable.

    -
      -
    • automatic: Automatically fetch managed Python installations when needed
      • +

      A relocatable virtual environment can be moved around and redistributed without invalidating its associated entrypoint and activation scripts.

      -
    • manual: Do not automatically fetch managed Python installations; require explicit installation
      • -
    -
    --color color-choice

    Control colors in output

    +

    Note that this can only be guaranteed for standard console_scripts and gui_scripts. Other scripts may be adjusted if they ship with a generic #!python[w] shebang, and binaries are left as-is.

    -

    [default: auto]

    -

    Possible values:

    +

    As a result of making the environment relocatable (by way of writing relative, rather than absolute paths), the entrypoints and scripts themselves will not be relocatable. In other words, copying those entrypoints and scripts to a location outside the environment will not work, as they reference paths relative to the environment itself.

    -
      -
    • auto: Enables colored output only when the output is going to a terminal or TTY with support
      • +
    --seed

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

    -
  • always: Enables colored output regardless of the detected environment
    • +

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

    -
  • never: Disables colored output
    • - -
    --config-file config-file

    The path to a uv.toml file to use for configuration.

    +
    --system-site-packages

    Give the virtual environment access to the system site packages directory.

    -

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +

    Unlike pip, when a virtual environment is created with --system-site-packages, uv will not take system site packages into account when running commands like uv pip list or uv pip install. The --system-site-packages flag will provide the virtual environment with access to the system site packages directory at runtime, but it will not affect the behavior of uv commands.

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    @@ -3811,30 +5279,6 @@ uv cache clean [OPTIONS] [PACKAGE]...

    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]

    @@ -3851,6 +5295,60 @@ uv cache clean [OPTIONS] [PACKAGE]...

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv cache prune @@ -3869,30 +5367,12 @@ uv cache prune [OPTIONS]

    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.

    +
    --ci

    Optimize the cache for persistence in a continuous integration environment, like GitHub Actions.

    -

    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.

    +

    By default, uv caches both the wheels that it builds from source and the pre-built wheels that it downloads directly, to enable high-performance package installation. In some scenarios, though, persisting pre-built wheels may be undesirable. For example, in GitHub Actions, it’s faster to omit pre-built wheels from the cache and instead have re-download them on each run. However, it typically is faster to cache wheels that are built from source, since the wheel building process can be expensive, especially for extension modules.

    -

    Possible values:

    +

    In --ci mode, uv will prune any pre-built wheels from the cache, but retain any wheels that were built from source.

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

    @@ -3909,6 +5389,60 @@ uv cache prune [OPTIONS]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ### uv cache dir @@ -3927,30 +5461,6 @@ uv cache dir [OPTIONS]

    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]

    @@ -3967,6 +5477,60 @@ uv cache dir [OPTIONS]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ## uv version @@ -3981,34 +5545,10 @@ uv version [OPTIONS]

    Options

    -
    --output-format output-format
    --cache-dir cache-dir

    Path to the cache 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.

    - -

    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]

    @@ -4025,6 +5565,60 @@ uv version [OPTIONS]

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --output-format output-format
    --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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +
    ## uv help @@ -4047,30 +5641,6 @@ uv help [OPTIONS] [COMMAND]...

    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]

    @@ -4087,5 +5657,61 @@ uv help [OPTIONS] [COMMAND]...

    While uv configuration can be included in a pyproject.toml file, it is not allowed in this context.

    +
    --help, -h

    Display the concise help for this command

    + +
    --native-tls

    Whether to load TLS certificates from the platform’s native certificate store.

    + +

    By default, uv loads certificates from the bundled webpki-roots crate. The webpki-roots are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).

    + +

    However, in some cases, you may want to use the platform’s native certificate store, especially if you’re relying on a corporate trust root (e.g., for a mandatory proxy) that’s included in your system’s certificate store.

    + +
    --no-cache, -n

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

    + +
    --no-config

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

    + +

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

    + +
    --no-pager

    Disable pager when printing help

    + +
    --no-progress

    Hide all progress outputs.

    + +

    For example, spinners or progress bars.

    + +
    --offline

    Disable network access.

    + +

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

    + +
    --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
      • +
    +
    --python-preference python-preference

    Whether to prefer uv-managed or system Python installations.

    + +

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

    + +

    Possible values:

    + +
      +
    • only-managed: Only use managed Python installations; never use system Python installations
      • + +
    • managed: Prefer managed Python installations over system Python installations
      • + +
    • system: Prefer system Python installations over managed Python installations
      • + +
    • only-system: Only use system Python installations; never use managed Python installations
      • +
    +
    --quiet, -q

    Do not print any output

    + +
    --verbose, -v

    Use verbose output.

    + +

    You can configure fine-grained logging using the RUST_LOG environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

    + +
    --version, -V

    Display the uv version

    +