From 39e2e3e74be265c6e38f5dc679fad749a2ac3470 Mon Sep 17 00:00:00 2001 From: Shunsuke Tsuchiya <84004458+shunsock@users.noreply.github.com> Date: Wed, 8 Oct 2025 22:46:11 +0900 Subject: [PATCH] Support `UV_WORKING_DIRECTORY` for setting `--directory` (#16125) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary This pull request enables the `--directory` option to accept environment variable: `UV_DIRECTORY` ### Motivation Currently, the `--project` option already supports environment variables, but --directory does not. The motivation for this change is the same as for the --project option. When using this option, it’s likely that the project root and the directory containing the uv project differ. In such cases, allowing environment variables makes it easier to avoid repeatedly specifying the directory in commands or task runners. ### Other PRs - PR for create `--project` option: https://github.com/astral-sh/uv/pull/12327 ## Test Plan ### no auto testing As with the --project option, no auto tests are included for this change. This is because the implementation relies on Clap’s built-in attribute functionality, and testing such behavior would effectively mean testing a third-party crate, which would be redundant. As long as the compiler accepts it, things should work as expected. ### testing manually i tested manually like [previous pull request](https://github.com/astral-sh/uv/pull/12327) ```shell $ cargo build --locked ./target/debug/uv init uv_directory $ mkdir uv_directory $ UV_DIRECTORY=uv_directory ./target/debug/uv sync Using CPython 3.14.0rc3 Creating virtual environment at: .venv Resolved 1 package in 15ms Audited in 0.04ms $ UV_DIRECTORY=uv_directory ./target/debug/uv run main.py Hello from uv-directory! $ ./target/debug/uv run main.py error: Failed to spawn: `main.py` Caused by: No such file or directory (os error 2) ``` --------- Co-authored-by: Zanie Blue --- crates/uv-cli/src/lib.rs | 2 +- crates/uv-static/src/env_vars.rs | 3 + crates/uv/tests/it/help.rs | 18 +++--- docs/reference/cli.md | 96 ++++++++++++++++---------------- docs/reference/environment.md | 4 ++ 5 files changed, 67 insertions(+), 56 deletions(-) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 87f06378b..ea82e4dfd 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -339,7 +339,7 @@ pub struct GlobalArgs { /// Relative paths are resolved with the given directory as the base. /// /// See `--project` to only change the project root directory. - #[arg(global = true, long)] + #[arg(global = true, long, env = EnvVars::UV_WORKING_DIRECTORY)] pub directory: Option, /// Run the command within the given project directory. diff --git a/crates/uv-static/src/env_vars.rs b/crates/uv-static/src/env_vars.rs index 5decfe439..15ddccf2d 100644 --- a/crates/uv-static/src/env_vars.rs +++ b/crates/uv-static/src/env_vars.rs @@ -876,6 +876,9 @@ impl EnvVars { /// Equivalent to the `--project` command-line argument. pub const UV_PROJECT: &'static str = "UV_PROJECT"; + /// Equivalent to the `--directory` command-line argument. + pub const UV_WORKING_DIRECTORY: &'static str = "UV_WORKING_DIRECTORY"; + /// Disable GitHub-specific requests that allow uv to skip `git fetch` in some circumstances. pub const UV_NO_GITHUB_FAST_PATH: &'static str = "UV_NO_GITHUB_FAST_PATH"; diff --git a/crates/uv/tests/it/help.rs b/crates/uv/tests/it/help.rs index b52ef2a88..9a70422dd 100644 --- a/crates/uv/tests/it/help.rs +++ b/crates/uv/tests/it/help.rs @@ -66,7 +66,7 @@ fn help() { --no-progress Hide all progress outputs [env: UV_NO_PROGRESS=] --directory - Change to the given directory prior to running the command + Change to the given directory prior to running the command [env: UV_WORKING_DIRECTORY=] --project Run the command within the given project directory [env: UV_PROJECT=] --config-file @@ -147,7 +147,7 @@ fn help_flag() { --no-progress Hide all progress outputs [env: UV_NO_PROGRESS=] --directory - Change to the given directory prior to running the command + Change to the given directory prior to running the command [env: UV_WORKING_DIRECTORY=] --project Run the command within the given project directory [env: UV_PROJECT=] --config-file @@ -227,7 +227,7 @@ fn help_short_flag() { --no-progress Hide all progress outputs [env: UV_NO_PROGRESS=] --directory - Change to the given directory prior to running the command + Change to the given directory prior to running the command [env: UV_WORKING_DIRECTORY=] --project Run the command within the given project directory [env: UV_PROJECT=] --config-file @@ -415,6 +415,8 @@ fn help_subcommand() { Relative paths are resolved with the given directory as the base. See `--project` to only change the project root directory. + + [env: UV_WORKING_DIRECTORY=] --project Run the command within the given project directory. @@ -676,6 +678,8 @@ fn help_subsubcommand() { Relative paths are resolved with the given directory as the base. See `--project` to only change the project root directory. + + [env: UV_WORKING_DIRECTORY=] --project Run the command within the given project directory. @@ -767,7 +771,7 @@ fn help_flag_subcommand() { --no-progress Hide all progress outputs [env: UV_NO_PROGRESS=] --directory - Change to the given directory prior to running the command + Change to the given directory prior to running the command [env: UV_WORKING_DIRECTORY=] --project Run the command within the given project directory [env: UV_PROJECT=] --config-file @@ -846,7 +850,7 @@ fn help_flag_subsubcommand() { --no-progress Hide all progress outputs [env: UV_NO_PROGRESS=] --directory - Change to the given directory prior to running the command + Change to the given directory prior to running the command [env: UV_WORKING_DIRECTORY=] --project Run the command within the given project directory [env: UV_PROJECT=] --config-file @@ -1008,7 +1012,7 @@ fn help_with_global_option() { --no-progress Hide all progress outputs [env: UV_NO_PROGRESS=] --directory - Change to the given directory prior to running the command + Change to the given directory prior to running the command [env: UV_WORKING_DIRECTORY=] --project Run the command within the given project directory [env: UV_PROJECT=] --config-file @@ -1131,7 +1135,7 @@ fn help_with_no_pager() { --no-progress Hide all progress outputs [env: UV_NO_PROGRESS=] --directory - Change to the given directory prior to running the command + Change to the given directory prior to running the command [env: UV_WORKING_DIRECTORY=] --project Run the command within the given project directory [env: UV_PROJECT=] --config-file diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 9dc523efb..f130ca0d4 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -88,7 +88,7 @@ uv auth login [OPTIONS]

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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:

@@ -163,7 +163,7 @@ uv auth logout [OPTIONS]

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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:

@@ -233,7 +233,7 @@ uv auth token [OPTIONS]

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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:

    @@ -308,7 +308,7 @@ uv auth dir [OPTIONS] [SERVICE]

    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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -394,7 +394,7 @@ uv run [OPTIONS] [COMMAND]

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.

-
--env-file env-file

Load environment variables from a .env file.

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -689,7 +689,7 @@ uv init [OPTIONS] [PATH]
--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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -817,7 +817,7 @@ uv add [OPTIONS] >

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.

-
--editable

Add the requirements as editable

+

May also be set with the UV_WORKING_DIRECTORY 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 both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

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.

@@ -1023,7 +1023,7 @@ uv remove [OPTIONS] ...

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.

-
--exclude-newer exclude-newer

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

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--exclude-newer exclude-newer

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

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

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) or local date (e.g., 2006-12-02) in your system's configured time zone.

@@ -1204,7 +1204,7 @@ uv version [OPTIONS] [VALUE]

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.

-
--dry-run

Don't write a new version to the pyproject.toml

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--dry-run

Don't write a new version to the pyproject.toml

Instead, the version will be displayed.

--exclude-newer exclude-newer

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

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

@@ -1393,7 +1393,7 @@ uv sync [OPTIONS]

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.

-
--dry-run

Perform a dry run, without writing the lockfile or modifying the project environment.

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--dry-run

Perform a dry run, without writing the lockfile or modifying the project environment.

In dry-run mode, uv will resolve the project's dependencies and report on the resulting changes to both the lockfile and the project environment, but will not modify either.

--exclude-newer exclude-newer

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

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

@@ -1656,7 +1656,7 @@ uv lock [OPTIONS]

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.

-
--dry-run

Perform a dry run, without writing the lockfile.

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--dry-run

Perform a dry run, without writing the lockfile.

In dry-run mode, uv will resolve the project's dependencies and report on the resulting changes, but will not write the lockfile to disk.

--exclude-newer exclude-newer

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

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

@@ -1824,7 +1824,7 @@ uv export [OPTIONS]

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.

-
--exclude-newer exclude-newer

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

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--exclude-newer exclude-newer

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

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

May also be set with the UV_EXCLUDE_NEWER environment variable.

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

Limit candidate packages for a specific package 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) or local date (e.g., 2006-12-02) in your system's configured time zone.

@@ -2026,7 +2026,7 @@ uv tree [OPTIONS]

[default: 255]

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

-
--exclude-newer exclude-newer

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

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--exclude-newer exclude-newer

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

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

May also be set with the UV_EXCLUDE_NEWER environment variable.

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

Limit candidate packages for a specific package 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) or local date (e.g., 2006-12-02) in your system's configured time zone.

@@ -2266,7 +2266,7 @@ uv format [OPTIONS] [-- ...]
--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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -2376,7 +2376,7 @@ uv tool run [OPTIONS] [COMMAND]

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.

-
--env-file env-file

Load environment variables from a .env file.

+

May also be set with the UV_WORKING_DIRECTORY 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.

--exclude-newer exclude-newer

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

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

@@ -2607,7 +2607,7 @@ uv tool install [OPTIONS]

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.

-
--editable, -e

Install the target package in editable mode, such that changes in the package's source directory are reflected without reinstallation

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--editable, -e

Install the target package in editable mode, such that changes in the package's source directory are reflected without reinstallation

--exclude-newer exclude-newer

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

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

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.

@@ -2831,7 +2831,7 @@ uv tool upgrade [OPTIONS] ...

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.

-
--exclude-newer exclude-newer

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

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--exclude-newer exclude-newer

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

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

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) or local date (e.g., 2006-12-02) in your system's configured time zone.

@@ -3023,7 +3023,7 @@ uv tool list [OPTIONS]

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -3090,7 +3090,7 @@ uv tool uninstall [OPTIONS] ...

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -3154,7 +3154,7 @@ uv tool update-shell [OPTIONS]

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -3231,7 +3231,7 @@ from the following environment variables, in order of preference:

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -3373,7 +3373,7 @@ uv python list [OPTIONS] [REQUEST]

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -3465,7 +3465,7 @@ uv python install [OPTIONS] [TARGETS]...
--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.

-
--force, -f

Replace existing Python executables during installation.

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--force, -f

Replace existing Python executables during installation.

By default, uv will refuse to replace executables that it does not manage.

Implies --reinstall.

--help, -h

Display the concise help for this command

@@ -3561,7 +3561,7 @@ uv python upgrade [OPTIONS] [TARGETS]...

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--help, -h

Display the concise help for this command

--install-dir, -i install-dir

The directory Python installations are stored in.

If provided, UV_PYTHON_INSTALL_DIR will need to be set for subsequent operations for uv to discover the Python installation.

See uv python dir to view the current Python installation directory. Defaults to ~/.local/share/uv/python.

@@ -3642,7 +3642,7 @@ uv python find [OPTIONS] [REQUEST]

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -3721,7 +3721,7 @@ uv python pin [OPTIONS] [REQUEST]

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.

-
--global

Update the global Python version pin.

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--global

Update the global Python version pin.

Writes the pinned Python version to a .python-version file in the uv user configuration directory: XDG_CONFIG_HOME/uv on Linux/macOS and %APPDATA%/uv on Windows.

When a local Python version pin is not found in the working directory or an ancestor directory, this version will be used instead.

--help, -h

Display the concise help for this command

@@ -3804,7 +3804,7 @@ from the following environment variables, in order of preference:

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -3869,7 +3869,7 @@ uv python uninstall [OPTIONS] ...

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--help, -h

Display the concise help for this command

--install-dir, -i install-dir

The directory where the Python was installed

May also be set with the UV_PYTHON_INSTALL_DIR 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.

@@ -3934,7 +3934,7 @@ uv python update-shell [OPTIONS]

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -4044,7 +4044,7 @@ uv pip compile [OPTIONS] >

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.

-
--emit-build-options

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

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--emit-build-options

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

--emit-find-links

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

--emit-index-annotation

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

--emit-index-url

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

@@ -4365,7 +4365,7 @@ uv pip sync [OPTIONS] ...

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.

-
--dry-run

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

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--dry-run

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

--exclude-newer exclude-newer

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

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

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.

@@ -4635,7 +4635,7 @@ uv pip install [OPTIONS] |--editable 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.

-
--dry-run

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

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--dry-run

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

--editable, -e editable

Install the editable package based on the provided local file path

--exact

Perform an exact sync, removing extraneous packages.

By default, installing will make the minimum necessary changes to satisfy the requirements. When enabled, uv will update the environment to exactly match the requirements, removing packages that are not included in the requirements.

@@ -4929,7 +4929,7 @@ uv pip uninstall [OPTIONS] >

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.

-
--dry-run

Perform a dry run, i.e., don't actually uninstall anything but print the resulting plan

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--dry-run

Perform a dry run, i.e., don't actually uninstall anything but print the resulting plan

--help, -h

Display the concise help for this command

--keyring-provider keyring-provider

Attempt to use keyring for authentication for remote requirements files.

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

@@ -5007,7 +5007,7 @@ uv pip freeze [OPTIONS]

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.

-
--exclude-editable

Exclude any editable packages from output

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--exclude-editable

Exclude any editable packages from output

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

@@ -5078,7 +5078,7 @@ uv pip list [OPTIONS]

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.

-
--editable, -e

Only include editable projects

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--editable, -e

Only include editable projects

--exclude exclude

Exclude the specified package(s) from the output

--exclude-editable

Exclude any editable packages from output

--exclude-newer exclude-newer

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

@@ -5190,7 +5190,7 @@ uv pip show [OPTIONS] [PACKAGE]...

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.

-
--files, -f

Show the full list of installed files for each package

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--files, -f

Show the full list of installed files for each package

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

@@ -5261,7 +5261,7 @@ uv pip tree [OPTIONS]

[default: 255]

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

-
--exclude-newer exclude-newer

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

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--exclude-newer exclude-newer

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

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

May also be set with the UV_EXCLUDE_NEWER environment variable.

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

@@ -5364,7 +5364,7 @@ uv pip check [OPTIONS]

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -5507,7 +5507,7 @@ uv venv [OPTIONS] [PATH]

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.

-
--exclude-newer exclude-newer

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

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--exclude-newer exclude-newer

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

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

May also be set with the UV_EXCLUDE_NEWER environment variable.

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

Limit candidate packages for a specific package 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) or local date (e.g., 2006-12-02) in your system's configured time zone.

@@ -5654,7 +5654,7 @@ uv build [OPTIONS] [SRC]

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.

-
--exclude-newer exclude-newer

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

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--exclude-newer exclude-newer

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

Accepts both RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z) and local dates in the same format (e.g., 2006-12-02) in your system's configured time zone.

May also be set with the UV_EXCLUDE_NEWER environment variable.

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

Limit candidate packages for a specific package 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) or local date (e.g., 2006-12-02) in your system's configured time zone.

@@ -5828,7 +5828,7 @@ uv publish [OPTIONS] [FILES]...

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.

-
--dry-run

Perform a dry run without uploading files.

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--dry-run

Perform a dry run without uploading files.

When enabled, the command will check for existing files if --check-url is provided, and will perform validation against the index if supported, but will not upload any files.

--help, -h

Display the concise help for this command

--index index

The name of an index in the configuration to use for publishing.

@@ -5944,7 +5944,7 @@ uv cache clean [OPTIONS] [PACKAGE]...

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.

-
--force

Force removal of the cache, ignoring in-use checks.

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--force

Force removal of the cache, ignoring in-use checks.

By default, uv cache clean will block until no process is reading the cache. When --force is used, uv cache clean will proceed without taking a lock.

--help, -h

Display the concise help for this command

--managed-python

Require use of uv-managed Python versions.

@@ -6007,7 +6007,7 @@ uv cache prune [OPTIONS]

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.

-
--force

Force removal of the cache, ignoring in-use checks.

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--force

Force removal of the cache, ignoring in-use checks.

By default, uv cache prune will block until no process is reading the cache. When --force is used, uv cache prune will proceed without taking a lock.

--help, -h

Display the concise help for this command

--managed-python

Require use of uv-managed Python versions.

@@ -6075,7 +6075,7 @@ uv cache dir [OPTIONS]

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -6154,7 +6154,7 @@ uv self update [OPTIONS] [TARGET_VERSION]

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.

-
--dry-run

Run without performing the update

+

May also be set with the UV_WORKING_DIRECTORY environment variable.

--dry-run

Run without performing the update

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

@@ -6214,7 +6214,7 @@ uv self version [OPTIONS]

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

@@ -6266,7 +6266,7 @@ uv generate-shell-completion [OPTIONS]

May also be set with the UV_INSECURE_HOST 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.

-
--managed-python

Require use of uv-managed Python versions.

+

May also be set with the UV_WORKING_DIRECTORY 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.

--no-managed-python

Disable use of uv-managed Python versions.

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

@@ -6312,7 +6312,7 @@ uv help [OPTIONS] [COMMAND]...

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.

-
--help, -h

Display the concise help for this command

+

May also be set with the UV_WORKING_DIRECTORY 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.

diff --git a/docs/reference/environment.md b/docs/reference/environment.md index 5eb75c939..b8d1934ee 100644 --- a/docs/reference/environment.md +++ b/docs/reference/environment.md @@ -560,6 +560,10 @@ created by `uv venv`. Note that `setuptools` and `wheel` are not included in Python 3.12+ environments. +### `UV_WORKING_DIRECTORY` + +Equivalent to the `--directory` command-line argument. + ## Externally defined variables