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.

--module, -m

Run a Python module.

Equivalent to python -m <module>.

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

May also be set with the UV_NO_BINARY environment variable.

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

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

May also be set with the UV_NO_BINARY_PACKAGE environment variable.

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

May also be set with the UV_NO_BUILD environment variable.

--no-build-isolation

Disable isolation when building source distributions.

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

May also be set with the UV_NO_BUILD_ISOLATION environment variable.

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

May also be set with the UV_NO_BUILD_PACKAGE 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-default-groups

Ignore the default dependency groups.

uv includes the groups defined in tool.uv.default-groups by default. This disables that option, however, specific groups can still be included with --group.

May also be set with the UV_NO_DEFAULT_GROUPS environment variable.

--no-dev

Disable the development dependency group.

This option is an alias of --no-group dev. See --no-default-groups to disable all default groups instead.

This option is only available when running in a project.

May also be set with the UV_NO_DEV environment variable.

--no-editable

Install any editable dependencies, including the project and any workspace members, as non-editable

May also be set with the UV_NO_EDITABLE environment variable.

--no-env-file

Avoid reading environment variables from a .env file

May also be set with the UV_NO_ENV_FILE environment variable.

--no-extra no-extra

Exclude the specified optional dependencies, if --all-extras is supplied.

May be provided multiple times.

--no-group no-group

Disable the specified dependency group.

This option always takes precedence over default groups, --all-groups, and --group.

May be provided multiple times.

May also be set with the UV_NO_GROUP environment variable.

--no-index

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

--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-project, --no_workspace

Avoid discovering the project or workspace.

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

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

--no-python-downloads

Disable automatic downloads of Python.

--no-sources

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

May also be set with the UV_NO_SOURCES environment variable.

--no-sync

Avoid syncing the virtual environment.

Implies --frozen, as the project dependencies will be ignored (i.e., the lockfile will not be updated, since the environment will not be synced regardless).

May also be set with the UV_NO_SYNC environment variable.

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

--only-dev

Only include the development dependency group.

The project and its dependencies will be omitted.

This option is an alias for --only-group dev. Implies --no-default-groups.

--only-group only-group

Only include dependencies from the specified dependency group.

The project and its dependencies will be omitted.

May be provided multiple times. Implies --no-default-groups.

--package package

Run the command in a specific package in the workspace.

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

May also be set with the UV_PRERELEASE environment variable.

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

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

May also be set with the UV_PYTHON environment variable.

--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 aarch64-apple-darwin.

When targeting macOS (Darwin), the default minimum version is 13.0. Use MACOSX_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting iOS, the default minimum version is 13.0. Use IPHONEOS_DEPLOYMENT_TARGET to specify a different minimum version, e.g., 14.0.

When targeting Android, the default minimum Android API level is 24. Use ANDROID_API_LEVEL to specify a different minimum version, e.g., 26.

WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform. Conversely, any distributions that are built from source may be incompatible with the target platform, as they will be built for the current platform. The --python-platform option is intended for advanced use cases.

Possible values:

  • windows: An alias for x86_64-pc-windows-msvc, the default target for Windows
  • linux: An alias for x86_64-unknown-linux-gnu, the default target for Linux
  • macos: An alias for aarch64-apple-darwin, the default target for macOS
  • x86_64-pc-windows-msvc: A 64-bit x86 Windows target
  • aarch64-pc-windows-msvc: An ARM64 Windows target
  • i686-pc-windows-msvc: A 32-bit x86 Windows target
  • x86_64-unknown-linux-gnu: An x86 Linux target. Equivalent to x86_64-manylinux_2_28
  • aarch64-apple-darwin: An ARM-based macOS target, as seen on Apple Silicon devices
  • x86_64-apple-darwin: An x86 macOS target
  • aarch64-unknown-linux-gnu: An ARM64 Linux target. Equivalent to aarch64-manylinux_2_28
  • aarch64-unknown-linux-musl: An ARM64 Linux target
  • x86_64-unknown-linux-musl: An x86_64 Linux target
  • riscv64-unknown-linux: A RISCV64 Linux target
  • x86_64-manylinux2014: An x86_64 target for the manylinux2014 platform. Equivalent to x86_64-manylinux_2_17
  • x86_64-manylinux_2_17: An x86_64 target for the manylinux_2_17 platform
  • x86_64-manylinux_2_28: An x86_64 target for the manylinux_2_28 platform
  • x86_64-manylinux_2_31: An x86_64 target for the manylinux_2_31 platform
  • x86_64-manylinux_2_32: An x86_64 target for the manylinux_2_32 platform
  • x86_64-manylinux_2_33: An x86_64 target for the manylinux_2_33 platform
  • x86_64-manylinux_2_34: An x86_64 target for the manylinux_2_34 platform
  • x86_64-manylinux_2_35: An x86_64 target for the manylinux_2_35 platform
  • x86_64-manylinux_2_36: An x86_64 target for the manylinux_2_36 platform
  • x86_64-manylinux_2_37: An x86_64 target for the manylinux_2_37 platform
  • x86_64-manylinux_2_38: An x86_64 target for the manylinux_2_38 platform
  • x86_64-manylinux_2_39: An x86_64 target for the manylinux_2_39 platform
  • x86_64-manylinux_2_40: An x86_64 target for the manylinux_2_40 platform
  • aarch64-manylinux2014: An ARM64 target for the manylinux2014 platform. Equivalent to aarch64-manylinux_2_17
  • aarch64-manylinux_2_17: An ARM64 target for the manylinux_2_17 platform
  • aarch64-manylinux_2_28: An ARM64 target for the manylinux_2_28 platform
  • aarch64-manylinux_2_31: An ARM64 target for the manylinux_2_31 platform
  • aarch64-manylinux_2_32: An ARM64 target for the manylinux_2_32 platform
  • aarch64-manylinux_2_33: An ARM64 target for the manylinux_2_33 platform
  • aarch64-manylinux_2_34: An ARM64 target for the manylinux_2_34 platform
  • aarch64-manylinux_2_35: An ARM64 target for the manylinux_2_35 platform
  • aarch64-manylinux_2_36: An ARM64 target for the manylinux_2_36 platform
  • aarch64-manylinux_2_37: An ARM64 target for the manylinux_2_37 platform
  • aarch64-manylinux_2_38: An ARM64 target for the manylinux_2_38 platform
  • aarch64-manylinux_2_39: An ARM64 target for the manylinux_2_39 platform
  • aarch64-manylinux_2_40: An ARM64 target for the manylinux_2_40 platform
  • aarch64-linux-android: An ARM64 Android target
  • x86_64-linux-android: An x86_64 Android target
  • wasm32-pyodide2024: A wasm32 target using the Pyodide 2024 platform. Meant for use with Python 3.12
  • arm64-apple-ios: An ARM64 target for iOS device
  • arm64-apple-ios-simulator: An ARM64 target for iOS simulator
  • x86_64-apple-ios-simulator: An x86_64 target for iOS simulator
--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.

--refresh

Refresh all cached data

--refresh-package refresh-package

Refresh cached data for a specific package

--reinstall, --force-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).

May also be set with the UV_RESOLUTION environment variable.

Possible values:

  • highest: Resolve the highest compatible version of each package
  • lowest: Resolve the lowest compatible version of each package
  • lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies
--script, -s

Run the given path as a Python script.

Using --script will attempt to parse the path as a PEP 723 script, irrespective of its extension.

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

Use verbose output.

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

--with, -w 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-editable with-editable

Run with the given packages installed in editable mode.

When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.

--with-requirements with-requirements

Run with the packages listed in the given files.

The following formats are supported: requirements.txt, .py files with inline metadata, and pylock.toml.

The same environment semantics as --with apply.

Using pyproject.toml, setup.py, or setup.cfg files is not allowed.

uv init

Create a new project.

Follows the pyproject.toml specification.

If a pyproject.toml already exists at the target, uv will exit with an error.

If a pyproject.toml is found in any of the parent directories of the target path, the project will be added as a workspace member of the parent.

Some project state is not created until needed, e.g., the project virtual environment (.venv) and lockfile (uv.lock) are lazily created during the first sync.

Usage

uv init [OPTIONS] [PATH]

Arguments

PATH

The path to use for the project/script.

Defaults to the current working directory when initializing an app or library; required when initializing a script. Accepts relative and absolute paths.

If a pyproject.toml is found in any of the parent directories of the target path, the project will be added as a workspace member of the parent, unless --no-workspace is provided.

Options

--allow-insecure-host, --trusted-host allow-insecure-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.

--app, --application

Create a project for an application.

This is the default behavior if --lib is not requested.

This project kind is for web servers, scripts, and command-line interfaces.

By default, an application is not intended to be built and distributed as a Python package. The --package option can be used to create an application that is distributable, e.g., if you want to distribute a command-line interface via PyPI.

--author-from author-from

Fill in the authors field in the pyproject.toml.

By default, uv will attempt to infer the author information from some sources (e.g., Git) (auto). Use --author-from git to only infer from Git configuration. Use --author-from none to avoid inferring the author information.

Possible values:

  • auto: Fetch the author information from some sources (e.g., Git) automatically
  • git: Fetch the author information from Git configuration only
  • none: Do not infer the author information
--bare

Only create a pyproject.toml.

Disables creating extra files like README.md, the src/ tree, .python-version files, etc.

--build-backend build-backend

Initialize a build-backend of choice for the project.

Implicitly sets --package.

May also be set with the UV_INIT_BUILD_BACKEND environment variable.

Possible values:

  • uv: Use uv as the project build backend
  • hatch: Use hatchling as the project build backend
  • flit: Use flit-core as the project build backend
  • pdm: Use pdm-backend as the project build backend
  • poetry: Use poetry-core as the project build backend
  • setuptools: Use setuptools as the project build backend
  • maturin: Use maturin as the project build backend
  • scikit: Use scikit-build-core as the project build backend
--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.

--description description

Set the project description

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

--lib, --library

Create a project for a library.

A library is a project that is intended to be built and distributed as a Python package.

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

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

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

Disable the description for the project

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

Do not set up the project to be built as a Python package.

Does not include a [build-system] for the project.

This is the default behavior when using --app.

--no-pin-python

Do not create a .python-version file for the project.

By default, uv will create a .python-version file containing the minor version of the discovered Python interpreter, which will cause subsequent uv commands to use that version.

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

--no-readme

Do not create a README.md file

--no-workspace, --no-project

Avoid discovering a workspace and 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.

May also be set with the UV_OFFLINE environment variable.

--package

Set up the project to be built as a Python package.

Defines a [build-system] for the project.

This is the default behavior when using --lib or --build-backend.

When using --app, this will include a [project.scripts] entrypoint and use a src/ project structure.

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

--python, -p python

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

See uv python to view supported request formats.

May also be set with the UV_PYTHON environment variable.

--quiet, -q

Use quiet output.

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

--script

Create a script.

A script is a standalone file with embedded metadata enumerating its dependencies, along with any Python version requirements, as defined in the PEP 723 specification.

PEP 723 scripts can be executed directly with uv run.

By default, adds a requirement on the system Python version; use --python to specify an alternative Python version requirement.

--vcs vcs

Initialize a version control system for the project.

By default, uv will initialize a Git repository (git). Use --vcs none to explicitly avoid initializing a version control system.

Possible values:

  • git: Use Git for version control
  • none: Do not use any version control system
--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 add

Add dependencies to the project.

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

If a given dependency exists already, it will be updated to the new version specifier unless it includes markers that differ from the existing specifier in which case another entry for the dependency will be added.

The lockfile and project environment will be updated to reflect the added dependencies. To skip updating the lockfile, use --frozen. To skip updating the environment, use --no-sync.

If any of the requested dependencies cannot be found, uv will exit with an error, unless the --frozen flag is provided, in which case uv will add the dependencies verbatim without checking that they exist or are compatible with the project.

uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.

Usage

uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>

Arguments

PACKAGES

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

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.

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

--bounds bounds

The kind of version specifier to use when adding dependencies.

When adding a dependency to the project, if no constraint or URL is provided, a constraint is added based on the latest compatible version of the package. By default, a lower bound constraint is used, e.g., >=1.2.3.

When --frozen is provided, no resolution is performed, and dependencies are always added without constraints.

This option is in preview and may change in any future release.

Possible values:

  • lower: Only a lower bound, e.g., >=1.2.3
  • major: Allow the same major version, similar to the semver caret, e.g., >=1.2.3, <2.0.0
  • minor: Allow the same minor version, similar to the semver tilde, e.g., >=1.2.3, <1.3.0
  • exact: Pin the exact version, e.g., ==1.2.3
--branch branch

Branch to use when adding a dependency from Git

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

--constraints, --constraint, -c constraints

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. The constraints will not be added to the project's pyproject.toml file, but will be respected during dependency resolution.

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

May also be set with the UV_CONSTRAINT environment variable.

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

--dev

Add the requirements to the development dependency group.

This option is an alias for --group dev.

May also be set with the UV_DEV environment variable.

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

--editable

Add the requirements as editable

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

Extras to enable for the dependency.

May be provided more than once.

To add this dependency to an optional extra instead, see --optional.

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

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

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

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

May also be set with the UV_EXTRA_INDEX_URL environment variable.

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

Add dependencies without re-locking the project.

The project environment will not be synced.

May also be set with the UV_FROZEN environment variable.

--group group

Add the requirements to the specified dependency group.

These requirements will not be included in the published metadata for the project.

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

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

Whether to use Git LFS when adding a dependency from Git

May also be set with the UV_GIT_LFS environment variable.

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

--marker, -m marker

Apply this marker to all added packages