Skip to content

CLI Reference

uv

An extremely fast Python package manager.

Usage

uv [OPTIONS] <COMMAND>

Commands

uv auth

Manage authentication

uv run

Run a command or script

uv init

Create a new project

uv add

Add dependencies to the project

uv remove

Remove dependencies from the project

uv version

Read or update the project's version

uv sync

Update the project's environment

uv lock

Update the project's lockfile

uv export

Export the project's lockfile to an alternate format

uv tree

Display the project's dependency tree

uv format

Format Python code in the project

uv tool

Run and install commands provided by Python packages

uv python

Manage Python versions and installations

uv pip

Manage Python packages with a pip-compatible interface

uv venv

Create a virtual environment

uv build

Build Python packages into source distributions and wheels

uv publish

Upload distributions to an index

uv cache

Manage uv's cache

uv self

Manage the uv executable

uv help

Display documentation for a command

uv auth

Manage authentication

Usage

uv auth [OPTIONS] <COMMAND>

Commands

uv auth login

Login to a service

uv auth logout

Logout of a service

uv auth token

Show the authentication token for a service

uv auth dir

Show the path to the uv credentials directory

uv auth login

Login to a service

Usage

uv auth login [OPTIONS] <SERVICE>

Arguments

SERVICE

The domain or URL of the service to log into

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.

To view the location of the cache directory, run uv cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, uv will automatically detect support for colors when writing to a terminal.

Possible values:

  • auto: Enables colored output only when the output is going to a terminal or TTY with 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.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--keyring-provider keyring-provider

The keyring provider to use for storage of credentials.

Only --keyring-provider native is supported for login, which uses the system keyring via an integration built into uv.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

  • disabled: Do not use keyring for credential lookup
  • subprocess: Use the keyring command for credential lookup
--managed-python

Require use of uv-managed Python versions.

By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.

May also be set with the UV_MANAGED_PYTHON environment variable.

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

May also be set with the UV_NATIVE_TLS environment variable.

--no-cache, --no-cache-dir, -n

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

May also be set with the UV_NO_CACHE environment variable.

--no-config

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

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

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of uv-managed Python versions.

Instead, uv will search for a suitable Python version on the system.

May also be set with the UV_NO_MANAGED_PYTHON environment variable.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

May also be set with the UV_NO_PROGRESS environment variable.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access.

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

May also be set with the UV_OFFLINE environment variable.

--password password

The password to use for the service.

Use - to read the password from stdin.

--project project

Discover a project in the given directory.

All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the uv pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.

--token, -t token

The token to use for the service.

The username will be set to __token__.

Use - to read the token from stdin.

--username, -u username

The username to use for the service

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

uv auth logout

Logout of a service

Usage

uv auth logout [OPTIONS] <SERVICE>

Arguments

SERVICE

The domain or URL of the service to logout from

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.

To view the location of the cache directory, run uv cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, uv will automatically detect support for colors when writing to a terminal.

Possible values:

  • auto: Enables colored output only when the output is going to a terminal or TTY with 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.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--keyring-provider keyring-provider

The keyring provider to use for storage of credentials.

Only --keyring-provider native is supported for logout, which uses the system keyring via an integration built into uv.

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

  • disabled: Do not use keyring for credential lookup
  • subprocess: Use the keyring command for credential lookup
--managed-python

Require use of uv-managed Python versions.

By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.

May also be set with the UV_MANAGED_PYTHON environment variable.

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

May also be set with the UV_NATIVE_TLS environment variable.

--no-cache, --no-cache-dir, -n

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

May also be set with the UV_NO_CACHE environment variable.

--no-config

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

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

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of uv-managed Python versions.

Instead, uv will search for a suitable Python version on the system.

May also be set with the UV_NO_MANAGED_PYTHON environment variable.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

May also be set with the UV_NO_PROGRESS environment variable.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access.

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

May also be set with the UV_OFFLINE environment variable.

--project project

Discover a project in the given directory.

All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the uv pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.

--username, -u username

The username to logout

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

uv auth token

Show the authentication token for a service

Usage

uv auth token [OPTIONS] <SERVICE>

Arguments

SERVICE

The domain or URL of the service to lookup

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.

To view the location of the cache directory, run uv cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, uv will automatically detect support for colors when writing to a terminal.

Possible values:

  • auto: Enables colored output only when the output is going to a terminal or TTY with 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.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--keyring-provider keyring-provider

The keyring provider to use for reading credentials

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

  • disabled: Do not use keyring for credential lookup
  • subprocess: Use the keyring command for credential lookup
--managed-python

Require use of uv-managed Python versions.

By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.

May also be set with the UV_MANAGED_PYTHON environment variable.

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

May also be set with the UV_NATIVE_TLS environment variable.

--no-cache, --no-cache-dir, -n

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

May also be set with the UV_NO_CACHE environment variable.

--no-config

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

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

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of uv-managed Python versions.

Instead, uv will search for a suitable Python version on the system.

May also be set with the UV_NO_MANAGED_PYTHON environment variable.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

May also be set with the UV_NO_PROGRESS environment variable.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access.

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

May also be set with the UV_OFFLINE environment variable.

--project project

Discover a project in the given directory.

All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the uv pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.

--username, -u username

The username to lookup

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

uv auth dir

Show the path to the uv credentials directory.

By default, credentials are stored in the uv data directory at $XDG_DATA_HOME/uv/credentials or $HOME/.local/share/uv/credentials on Unix and %APPDATA%\uv\data\credentials on Windows.

The credentials directory may be overridden with $UV_CREDENTIALS_DIR.

Credentials are only stored in this directory when the plaintext backend is used, as opposed to the native backend, which uses the system keyring.

Usage

uv auth dir [OPTIONS] [SERVICE]

Arguments

SERVICE

The domain or URL of the service to lookup

Options

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.

To view the location of the cache directory, run uv cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, uv will automatically detect support for colors when writing to a terminal.

Possible values:

  • auto: Enables colored output only when the output is going to a terminal or TTY with 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.

May also be set with the UV_CONFIG_FILE environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--help, -h

Display the concise help for this command

--managed-python

Require use of uv-managed Python versions.

By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.

May also be set with the UV_MANAGED_PYTHON environment variable.

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

May also be set with the UV_NATIVE_TLS environment variable.

--no-cache, --no-cache-dir, -n

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

May also be set with the UV_NO_CACHE environment variable.

--no-config

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

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

May also be set with the UV_NO_CONFIG environment variable.

--no-managed-python

Disable use of uv-managed Python versions.

Instead, uv will search for a suitable Python version on the system.

May also be set with the UV_NO_MANAGED_PYTHON environment variable.

--no-progress

Hide all progress outputs.

For example, spinners or progress bars.

May also be set with the UV_NO_PROGRESS environment variable.

--no-python-downloads

Disable automatic downloads of Python.

--offline

Disable network access.

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

May also be set with the UV_OFFLINE environment variable.

--project project

Discover a project in the given directory.

All pyproject.toml, uv.toml, and .python-version files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (.venv).

Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.

See --directory to change the working directory entirely.

This setting has no effect when used in the uv pip interface.

May also be set with the UV_PROJECT environment variable.

--quiet, -q

Use quiet output.

Repeating this option, e.g., -qq, will enable a silent mode in which uv will write no output to stdout.

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

uv run

Run a command or script.

Ensures that the command runs in a Python environment.

When used with a file ending in .py or an HTTP(S) URL, the file will be treated as a script and run with a Python interpreter, i.e., uv run file.py is equivalent to uv run python file.py. For URLs, the script is temporarily downloaded before execution. If the script contains inline dependency metadata, it will be installed into an isolated, ephemeral environment. When used with -, the input will be read from stdin, and treated as a Python script.

When used in a project, the project environment will be created and updated before invoking the command.

When used outside a project, if a virtual environment can be found in the current directory or a parent directory, the command will be run in that environment. Otherwise, the command will be run in the environment of the discovered interpreter.

Arguments following the command (or script) are not interpreted as arguments to uv. All options to uv must be provided before the command, e.g., uv run --verbose foo. A -- can be used to separate the command from uv options for clarity, e.g., uv run --python 3.12 -- python.

Usage

uv run [OPTIONS] [COMMAND]

Options

--active

Prefer the active virtual environment over the project's virtual environment.

If the project virtual environment is active or no virtual environment is active, this has no effect.

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

--all-groups

Include dependencies from all dependency groups.

--no-group can be used to exclude specific groups.

--all-packages

Run the command with all workspace members installed.

The workspace's environment (.venv) is updated to include all workspace members.

Any extras or groups specified via --extra, --group, or related options will be applied to all workspace members.

--allow-insecure-host, --trusted-host allow-insecure-host

Allow insecure connections to a host.

Can be provided multiple times.

Expects to receive either a hostname (e.g., localhost), a host-port pair (e.g., localhost:8080), or a URL (e.g., https://localhost).

WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use --allow-insecure-host in a secure network with verified sources, as it bypasses SSL verification and could expose you to MITM attacks.

May also be set with the UV_INSECURE_HOST environment variable.

--cache-dir cache-dir

Path to the cache directory.

Defaults to $XDG_CACHE_HOME/uv or $HOME/.cache/uv on macOS and Linux, and %LOCALAPPDATA%\uv\cache on Windows.

To view the location of the cache directory, run uv cache dir.

May also be set with the UV_CACHE_DIR environment variable.

--color color-choice

Control the use of color in output.

By default, uv will automatically detect support for colors when writing to a terminal.

Possible values:

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

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.

May also be set with the UV_COMPILE_BYTECODE environment variable.

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

May also be set with the UV_CONFIG_FILE environment variable.

--config-setting, --config-settings, -C config-setting

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

--config-settings-package, --config-settings-package config-settings-package

Settings to pass to the PEP 517 build backend for a specific package, specified as PACKAGE:KEY=VALUE pairs

--default-index default-index

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

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

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

May also be set with the UV_DEFAULT_INDEX environment variable.

--directory directory

Change to the given directory prior to running the command.

Relative paths are resolved with the given directory as the base.

See --project to only change the project root directory.

May also be set with the UV_WORKING_DIR environment variable.

--env-file env-file

Load environment variables from a .env file.

Can be provided multiple times, with subsequent files overriding values defined in previous files.

May also be set with the UV_ENV_FILE environment variable.

--exact

Perform an exact sync, removing extraneous packages.

When enabled, uv will remove any extraneous packages from the environment. By default, uv run will make the minimum necessary changes to satisfy the requirements.

--exclude-newer exclude-newer

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

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

May also be set with the UV_EXCLUDE_NEWER environment variable.

--exclude-newer-package exclude-newer-package

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

Accepts package-date pairs in the format PACKAGE=DATE, where DATE is an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z), a local date in the same format (e.g., 2006-12-02) resolved based on your system's configured time zone, a "friendly" duration (e.g., 24 hours, 1 week, 30 days), or an ISO 8601 duration (e.g., PT24H, P7D, P30D).

Durations do not respect semantics of the local time zone and are always resolved to a fixed number of seconds assuming that a day is 24 hours (e.g., DST transitions are ignored). Calendar units such as months and years are not allowed.

Can be provided multiple times for different packages.

--extra extra

Include optional dependencies from the specified extra name.

May be provided more than once.

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

This option is only available when running in a project.

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

(Deprecated: use --index instead) Extra URLs of package indexes to use, in addition to --index-url.

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

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

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

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

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

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

May also be set with the UV_FIND_LINKS environment variable.

--fork-strategy fork-strategy

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

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

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

May also be set with the UV_FORK_STRATEGY environment variable.

Possible values:

  • fewest: Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or platforms
  • requires-python: Optimize for selecting latest supported version of each package, for each supported Python version
--frozen

Run without updating the uv.lock file.

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

May also be set with the UV_FROZEN environment variable.

--group group

Include dependencies from the specified dependency group.

May be provided multiple times.

--gui-script

Run the given path as a Python GUI script.

Using --gui-script will attempt to parse the path as a PEP 723 script and run it with pythonw.exe, irrespective of its extension. Only available on Windows.

--help, -h

Display the concise help for this command

--index index

The URLs to use when resolving dependencies, in addition to the default index.

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

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

Index names are not supported as values. Relative paths must be disambiguated from index names with ./ or ../ on Unix or .\\, ..\\, ./ or ../ on Windows.

May also be set with the UV_INDEX environment variable.

--index-strategy index-strategy

The strategy to use when resolving against multiple index URLs.

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

May also be set with the UV_INDEX_STRATEGY environment variable.

Possible values:

  • first-index: Only use results from the first index that returns a match for a given package 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

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

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

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

May also be set with the UV_INDEX_URL environment variable.

--isolated

Run the command in an isolated virtual environment.

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

An editable installation is still used for the project.

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

May also be set with the UV_ISOLATED environment variable.

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

May also be set with the UV_KEYRING_PROVIDER environment variable.

Possible values:

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

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

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

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

May also be set with the UV_LINK_MODE environment variable.

Possible values:

  • clone: Clone (i.e., copy-on-write) packages from the wheel into the site-packages 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.

May also be set with the UV_LOCKED environment variable.

--managed-python

Require use of uv-managed Python versions.

By default, uv prefers using Python versions it manages. However, it will use system Python versions if a uv-managed Python is not installed. This option disables use of system Python versions.

May also be set with the UV_MANAGED_PYTHON environment variable.