From 84d57f2ee9bb6f452e3be74c658b2e0096b1dc30 Mon Sep 17 00:00:00 2001 From: konsti Date: Thu, 7 Aug 2025 15:56:59 +0200 Subject: [PATCH] Ensure symlink warning is shown (#15126) Fixes #15115, see also https://github.com/clap-rs/clap/discussions/6092 image --- crates/uv-cli/src/lib.rs | 25 +++++++++++++++++++++++++ crates/uv-install-wheel/src/linker.rs | 5 ----- crates/uv-settings/src/settings.rs | 12 +++++++++++- docs/reference/cli.md | 16 ++++++++++++++++ docs/reference/settings.md | 14 ++++++++++++-- uv.schema.json | 6 +++--- 6 files changed, 67 insertions(+), 11 deletions(-) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index f436f41ba..120e098e3 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -2769,6 +2769,11 @@ pub struct VenvArgs { /// /// 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 clear`) + /// will break all installed packages by way of removing the underlying source files. Use + /// symlinks with caution. #[arg(long, value_enum, env = EnvVars::UV_LINK_MODE)] pub link_mode: Option, @@ -4808,6 +4813,11 @@ pub struct ToolUpgradeArgs { /// /// 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 clear`) + /// will break all installed packages by way of removing the underlying source files. Use + /// symlinks with caution. #[arg( long, value_enum, @@ -5612,6 +5622,11 @@ pub struct InstallerArgs { /// /// 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 clear`) + /// will break all installed packages by way of removing the underlying source files. Use + /// symlinks with caution. #[arg( long, value_enum, @@ -5824,6 +5839,11 @@ pub struct ResolverArgs { /// /// 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 clear`) + /// will break all installed packages by way of removing the underlying source files. Use + /// symlinks with caution. #[arg( long, value_enum, @@ -6028,6 +6048,11 @@ pub struct ResolverInstallerArgs { /// /// 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 clear`) + /// will break all installed packages by way of removing the underlying source files. Use + /// symlinks with caution. #[arg( long, value_enum, diff --git a/crates/uv-install-wheel/src/linker.rs b/crates/uv-install-wheel/src/linker.rs index 37e37199b..cc08c17da 100644 --- a/crates/uv-install-wheel/src/linker.rs +++ b/crates/uv-install-wheel/src/linker.rs @@ -27,11 +27,6 @@ pub enum LinkMode { /// Hard link packages from the wheel into the `site-packages` directory. Hardlink, /// Symbolically link packages from the wheel into the `site-packages` directory. - /// - /// WARNING: The use of symlinks is discouraged, as they create tight coupling between the - /// cache and the target environment. For example, clearing the cache (`uv cache clear`) will - /// break all installed packages by way of removing the underlying source files. Use symlinks - /// with caution. Symlink, } diff --git a/crates/uv-settings/src/settings.rs b/crates/uv-settings/src/settings.rs index 5eaa7e2eb..b2c10107b 100644 --- a/crates/uv-settings/src/settings.rs +++ b/crates/uv-settings/src/settings.rs @@ -639,7 +639,7 @@ pub struct ResolverInstallerOptions { default = "[]", value_type = "dict", example = r#" - [extra-build-dependencies] + [extra-build-dependencies] pytest = ["setuptools"] "# )] @@ -685,6 +685,11 @@ pub struct ResolverInstallerOptions { /// /// 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 clear`) + /// will break all installed packages by way of removing the underlying source files. Use + /// symlinks with caution. #[option( default = "\"clone\" (macOS) or \"hardlink\" (Linux, Windows)", value_type = "str", @@ -1568,6 +1573,11 @@ pub struct PipOptions { /// /// 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 clear`) + /// will break all installed packages by way of removing the underlying source files. Use + /// symlinks with caution. #[option( default = "\"clone\" (macOS) or \"hardlink\" (Linux, Windows)", value_type = "str", diff --git a/docs/reference/cli.md b/docs/reference/cli.md index f75f629d2..5b30b98be 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -151,6 +151,7 @@ uv run [OPTIONS] [COMMAND]
  • 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 clear) 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
      • @@ -509,6 +510,7 @@ uv add [OPTIONS] >
    • 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 clear) 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
      • @@ -702,6 +704,7 @@ uv remove [OPTIONS] ...
    • 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 clear) 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
      • @@ -883,6 +886,7 @@ uv version [OPTIONS] [VALUE]
    • 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 clear) 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
      • @@ -1080,6 +1084,7 @@ uv sync [OPTIONS]
    • 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 clear) 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
      • @@ -1321,6 +1326,7 @@ uv lock [OPTIONS]
    --link-mode link-mode

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

    This option is only used when building source distributions.

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

    +

    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 clear) 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
      • @@ -1499,6 +1505,7 @@ uv export [OPTIONS]
    --link-mode link-mode

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

    This option is only used when building source distributions.

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

    +

    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 clear) 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
      • @@ -1690,6 +1697,7 @@ uv tree [OPTIONS]
    --link-mode link-mode

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

    This option is only used when building source distributions.

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

    +

    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 clear) 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
      • @@ -1953,6 +1961,7 @@ uv tool run [OPTIONS] [COMMAND]
    • 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 clear) 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
      • @@ -2127,6 +2136,7 @@ uv tool install [OPTIONS]
    • 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 clear) 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
      • @@ -2293,6 +2303,7 @@ uv tool upgrade [OPTIONS] ...
    • 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 clear) 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
      • @@ -3465,6 +3476,7 @@ uv pip compile [OPTIONS] >
    --link-mode link-mode

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

    This option is only used when building source distributions.

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

    +

    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 clear) 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
      • @@ -3755,6 +3767,7 @@ uv pip sync [OPTIONS] ...
    • 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 clear) 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
      • @@ -4024,6 +4037,7 @@ uv pip install [OPTIONS] |--editable 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 clear) 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
      • @@ -4812,6 +4826,7 @@ uv venv [OPTIONS] [PATH]
    --link-mode link-mode

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

    This option is only used for installing seed packages.

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

    +

    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 clear) 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
      • @@ -4967,6 +4982,7 @@ uv build [OPTIONS] [SRC]
    --link-mode link-mode

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

    This option is only used when building source distributions.

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

    +

    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 clear) 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
      • diff --git a/docs/reference/settings.md b/docs/reference/settings.md index bbd1126bb..97e9656b0 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -1188,13 +1188,13 @@ additional packages. This is useful for packages that assume the presence of pac ```toml [tool.uv] - [extra-build-dependencies] + [extra-build-dependencies] pytest = ["setuptools"] ``` === "uv.toml" ```toml - [extra-build-dependencies] + [extra-build-dependencies] pytest = ["setuptools"] ``` @@ -1483,6 +1483,11 @@ 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 clear`) +will break all installed packages by way of removing the underlying source files. Use +symlinks with caution. + **Default value**: `"clone" (macOS) or "hardlink" (Linux, Windows)` **Possible values**: @@ -3042,6 +3047,11 @@ 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 clear`) +will break all installed packages by way of removing the underlying source files. Use +symlinks with caution. + **Default value**: `"clone" (macOS) or "hardlink" (Linux, Windows)` **Possible values**: diff --git a/uv.schema.json b/uv.schema.json index f3cb65fae..94220a608 100644 --- a/uv.schema.json +++ b/uv.schema.json @@ -323,7 +323,7 @@ ] }, "link-mode": { - "description": "The method to use when installing packages from the global cache.\n\nDefaults to `clone` (also known as Copy-on-Write) on macOS, and `hardlink` on Linux and\nWindows.", + "description": "The method to use when installing packages from the global cache.\n\nDefaults to `clone` (also known as Copy-on-Write) on macOS, and `hardlink` on Linux and\nWindows.\n\nWARNING: The use of symlink link mode is discouraged, as they create tight coupling between\nthe cache and the target environment. For example, clearing the cache (`uv cache clear`)\nwill break all installed packages by way of removing the underlying source files. Use\nsymlinks with caution.", "anyOf": [ { "$ref": "#/definitions/LinkMode" @@ -1169,7 +1169,7 @@ "const": "hardlink" }, { - "description": "Symbolically link packages from the wheel into the `site-packages` directory.\n\nWARNING: The use of symlinks is discouraged, as they create tight coupling between the\ncache and the target environment. For example, clearing the cache (`uv cache clear`) will\nbreak all installed packages by way of removing the underlying source files. Use symlinks\nwith caution.", + "description": "Symbolically link packages from the wheel into the `site-packages` directory.", "type": "string", "const": "symlink" } @@ -1482,7 +1482,7 @@ ] }, "link-mode": { - "description": "The method to use when installing packages from the global cache.\n\nDefaults to `clone` (also known as Copy-on-Write) on macOS, and `hardlink` on Linux and\nWindows.", + "description": "The method to use when installing packages from the global cache.\n\nDefaults to `clone` (also known as Copy-on-Write) on macOS, and `hardlink` on Linux and\nWindows.\n\nWARNING: The use of symlink link mode is discouraged, as they create tight coupling between\nthe cache and the target environment. For example, clearing the cache (`uv cache clear`)\nwill break all installed packages by way of removing the underlying source files. Use\nsymlinks with caution.", "anyOf": [ { "$ref": "#/definitions/LinkMode"