diff --git a/crates/uv-cache/src/cli.rs b/crates/uv-cache/src/cli.rs index cd6461c003e8..a21f7905cc47 100644 --- a/crates/uv-cache/src/cli.rs +++ b/crates/uv-cache/src/cli.rs @@ -8,7 +8,8 @@ use crate::Cache; #[derive(Parser, Debug, Clone)] pub struct CacheArgs { - /// Avoid reading from or writing to the cache. + /// Avoid reading from or writing to the cache, instead using a temporary directory for the + /// duration of the operation. #[arg( global = true, long, diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 20b8e84bc8b2..ac7f1b06da25 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -111,8 +111,8 @@ pub struct GlobalArgs { /// 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` + /// 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, @@ -131,7 +131,8 @@ pub struct GlobalArgs { #[arg(global = true, long, overrides_with("offline"), hide = true)] pub no_offline: bool, - /// Whether to prefer using Python from uv or on the system. + /// Whether to prefer using Python installations that are already present on the system, or + /// those that are downloaded and installed by uv. #[arg(global = true, long)] pub python_preference: Option, @@ -216,7 +217,7 @@ pub enum Commands { after_long_help = "" )] Cache(CacheNamespace), - /// Manage the `uv` executable. + /// Manage the uv executable. #[command(name = "self")] #[cfg(feature = "self-update")] Self_(SelfNamespace), @@ -258,7 +259,7 @@ pub struct SelfNamespace { #[derive(Subcommand)] #[cfg(feature = "self-update")] pub enum SelfCommand { - /// Update `uv` to the latest version. + /// Update uv to the latest version. Update, } @@ -454,7 +455,7 @@ fn parse_maybe_file_path(input: &str) -> Result, String> { pub struct PipCompileArgs { /// Include all packages listed in the given `requirements.in` files. /// - /// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, `uv` will + /// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will /// extract the requirements for the relevant project. /// /// If `-` is provided, then requirements will be read from stdin. @@ -516,7 +517,7 @@ pub struct PipCompileArgs { /// Include extras in the output file. /// - /// By default, `uv` strips extras, as any packages pulled in by the extras are already included + /// By default, uv strips extras, as any packages pulled in by the extras are already included /// as dependencies in the output file directly. Further, output files generated with /// `--no-strip-extras` cannot be used as constraints files in `install` and `sync` invocations. #[arg(long, overrides_with("strip_extras"))] @@ -527,7 +528,7 @@ pub struct PipCompileArgs { /// Include environment markers in the output file. /// - /// By default, `uv` strips environment markers, as the resolution generated by `compile` is + /// By default, uv strips environment markers, as the resolution generated by `compile` is /// only guaranteed to be correct for the target environment. #[arg(long, overrides_with("strip_markers"))] pub no_strip_markers: bool, @@ -561,7 +562,7 @@ pub struct PipCompileArgs { /// The Python interpreter against which to compile the requirements. /// - /// By default, `uv` uses the virtual environment in the current working directory or any parent + /// By default, uv uses the virtual environment in the current working directory or any parent /// directory, falling back to searching for a Python executable in `PATH`. The `--python` /// option allows you to specify a different interpreter. /// @@ -575,9 +576,9 @@ pub struct PipCompileArgs { /// Install packages into the system Python. /// - /// By default, `uv` uses the virtual environment in the current working directory or any parent + /// By default, uv uses the virtual environment in the current working directory or any parent /// directory, falling back to searching for a Python executable in `PATH`. The `--system` - /// option instructs `uv` to avoid using a virtual environment Python and restrict its search to + /// option instructs uv to avoid using a virtual environment Python and restrict its search to /// the system path. #[arg( long, @@ -752,7 +753,7 @@ pub struct PipCompileArgs { pub struct PipSyncArgs { /// Include all packages listed in the given `requirements.txt` files. /// - /// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, `uv` will + /// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will /// extract the requirements for the relevant project. /// /// If `-` is provided, then requirements will be read from stdin. @@ -795,7 +796,7 @@ pub struct PipSyncArgs { /// The Python interpreter into which packages should be installed. /// - /// By default, `uv` installs into the virtual environment in the current working directory or + /// By default, uv installs into the virtual environment in the current working directory or /// any parent directory. The `--python` option allows you to specify a different interpreter, /// which is intended for use in continuous integration (CI) environments or other automated /// workflows. @@ -810,8 +811,8 @@ pub struct PipSyncArgs { /// Install packages into the system Python. /// - /// By default, `uv` installs into the virtual environment in the current working directory or - /// any parent directory. The `--system` option instructs `uv` to instead use the first Python + /// By default, uv installs into the virtual environment in the current working directory or + /// any parent directory. The `--system` option instructs uv to instead use the first Python /// found in the system `PATH`. /// /// WARNING: `--system` is intended for use in continuous integration (CI) environments and @@ -827,12 +828,12 @@ pub struct PipSyncArgs { #[arg(long, overrides_with("system"), hide = true)] pub no_system: bool, - /// Allow `uv` to modify an `EXTERNALLY-MANAGED` Python installation. + /// Allow uv to modify an `EXTERNALLY-MANAGED` Python installation. /// /// WARNING: `--break-system-packages` is intended for use in continuous integration (CI) /// environments, when installing into Python installations that are managed by an external /// package manager, like `apt`. It should be used with caution, as such Python installations - /// explicitly recommend against modifications by other package managers (like `uv` or `pip`). + /// explicitly recommend against modifications by other package managers (like uv or `pip`). #[arg( long, env = "UV_BREAK_SYSTEM_PACKAGES", @@ -983,7 +984,7 @@ pub struct PipInstallArgs { /// Install all packages listed in the given `requirements.txt` files. /// - /// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, `uv` will + /// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will /// extract the requirements for the relevant project. /// /// If `-` is provided, then requirements will be read from stdin. @@ -1067,7 +1068,7 @@ pub struct PipInstallArgs { /// The Python interpreter into which packages should be installed. /// - /// By default, `uv` installs into the virtual environment in the current working directory or + /// By default, uv installs into the virtual environment in the current working directory or /// any parent directory. The `--python` option allows you to specify a different interpreter, /// which is intended for use in continuous integration (CI) environments or other automated /// workflows. @@ -1082,8 +1083,8 @@ pub struct PipInstallArgs { /// Install packages into the system Python. /// - /// By default, `uv` installs into the virtual environment in the current working directory or - /// any parent directory. The `--system` option instructs `uv` to instead use the first Python + /// By default, uv installs into the virtual environment in the current working directory or + /// any parent directory. The `--system` option instructs uv to instead use the first Python /// found in the system `PATH`. /// /// WARNING: `--system` is intended for use in continuous integration (CI) environments and @@ -1099,12 +1100,12 @@ pub struct PipInstallArgs { #[arg(long, overrides_with("system"), hide = true)] pub no_system: bool, - /// Allow `uv` to modify an `EXTERNALLY-MANAGED` Python installation. + /// Allow uv to modify an `EXTERNALLY-MANAGED` Python installation. /// /// WARNING: `--break-system-packages` is intended for use in continuous integration (CI) /// environments, when installing into Python installations that are managed by an external /// package manager, like `apt`. It should be used with caution, as such Python installations - /// explicitly recommend against modifications by other package managers (like `uv` or `pip`). + /// explicitly recommend against modifications by other package managers (like uv or `pip`). #[arg( long, env = "UV_BREAK_SYSTEM_PACKAGES", @@ -1252,7 +1253,7 @@ pub struct PipUninstallArgs { /// The Python interpreter from which packages should be uninstalled. /// - /// By default, `uv` uninstalls from the virtual environment in the current working directory or + /// By default, uv uninstalls from the virtual environment in the current working directory or /// any parent directory. The `--python` option allows you to specify a different interpreter, /// which is intended for use in continuous integration (CI) environments or other automated /// workflows. @@ -1267,7 +1268,7 @@ pub struct PipUninstallArgs { /// Attempt to use `keyring` for authentication for remote requirements files. /// - /// At present, only `--keyring-provider subprocess` is supported, which configures `uv` to + /// At present, only `--keyring-provider subprocess` is supported, which configures uv to /// use the `keyring` CLI to handle authentication. /// /// Defaults to `disabled`. @@ -1276,8 +1277,8 @@ pub struct PipUninstallArgs { /// Use the system Python to uninstall packages. /// - /// By default, `uv` uninstalls from the virtual environment in the current working directory or - /// any parent directory. The `--system` option instructs `uv` to instead use the first Python + /// By default, uv uninstalls from the virtual environment in the current working directory or + /// any parent directory. The `--system` option instructs uv to instead use the first Python /// found in the system `PATH`. /// /// WARNING: `--system` is intended for use in continuous integration (CI) environments and @@ -1293,12 +1294,12 @@ pub struct PipUninstallArgs { #[arg(long, overrides_with("system"), hide = true)] pub no_system: bool, - /// Allow `uv` to modify an `EXTERNALLY-MANAGED` Python installation. + /// Allow uv to modify an `EXTERNALLY-MANAGED` Python installation. /// /// WARNING: `--break-system-packages` is intended for use in continuous integration (CI) /// environments, when installing into Python installations that are managed by an external /// package manager, like `apt`. It should be used with caution, as such Python installations - /// explicitly recommend against modifications by other package managers (like `uv` or `pip`). + /// explicitly recommend against modifications by other package managers (like uv or `pip`). #[arg( long, env = "UV_BREAK_SYSTEM_PACKAGES", @@ -1339,7 +1340,7 @@ pub struct PipFreezeArgs { /// The Python interpreter for which packages should be listed. /// - /// By default, `uv` lists packages in the currently activated virtual environment, or a virtual + /// By default, uv lists packages in the currently activated virtual environment, or a virtual /// environment (`.venv`) located in the current working directory or any parent directory, /// falling back to the system Python if no virtual environment is found. /// @@ -1353,10 +1354,10 @@ pub struct PipFreezeArgs { /// List packages for the system Python. /// - /// By default, `uv` lists packages in the currently activated virtual environment, or a virtual + /// By default, uv lists packages in the currently activated virtual environment, or a virtual /// environment (`.venv`) located in the current working directory or any parent directory, /// falling back to the system Python if no virtual environment is found. The `--system` option - /// instructs `uv` to use the first Python found in the system `PATH`. + /// instructs uv to use the first Python found in the system `PATH`. /// /// WARNING: `--system` is intended for use in continuous integration (CI) environments and /// should be used with caution. @@ -1404,7 +1405,7 @@ pub struct PipListArgs { /// The Python interpreter for which packages should be listed. /// - /// By default, `uv` lists packages in the currently activated virtual environment, or a virtual + /// By default, uv lists packages in the currently activated virtual environment, or a virtual /// environment (`.venv`) located in the current working directory or any parent directory, /// falling back to the system Python if no virtual environment is found. /// @@ -1418,10 +1419,10 @@ pub struct PipListArgs { /// List packages for the system Python. /// - /// By default, `uv` lists packages in the currently activated virtual environment, or a virtual + /// By default, uv lists packages in the currently activated virtual environment, or a virtual /// environment (`.venv`) located in the current working directory or any parent directory, /// falling back to the system Python if no virtual environment is found. The `--system` option - /// instructs `uv` to use the first Python found in the system `PATH`. + /// instructs uv to use the first Python found in the system `PATH`. /// /// WARNING: `--system` is intended for use in continuous integration (CI) environments and /// should be used with caution. @@ -1445,7 +1446,7 @@ pub struct PipListArgs { pub struct PipCheckArgs { /// The Python interpreter for which packages should be listed. /// - /// By default, `uv` lists packages in the currently activated virtual environment, or a virtual + /// By default, uv lists packages in the currently activated virtual environment, or a virtual /// environment (`.venv`) located in the current working directory or any parent directory, /// falling back to the system Python if no virtual environment is found. /// @@ -1459,10 +1460,10 @@ pub struct PipCheckArgs { /// List packages for the system Python. /// - /// By default, `uv` lists packages in the currently activated virtual environment, or a virtual + /// By default, uv lists packages in the currently activated virtual environment, or a virtual /// environment (`.venv`) located in the current working directory or any parent directory, /// falling back to the system Python if no virtual environment is found. The `--system` option - /// instructs `uv` to use the first Python found in the system `PATH`. + /// instructs uv to use the first Python found in the system `PATH`. /// /// WARNING: `--system` is intended for use in continuous integration (CI) environments and /// should be used with caution. @@ -1494,7 +1495,7 @@ pub struct PipShowArgs { /// The Python interpreter for which packages should be listed. /// - /// By default, `uv` lists packages in the currently activated virtual environment, or a virtual + /// By default, uv lists packages in the currently activated virtual environment, or a virtual /// environment (`.venv`) located in the current working directory or any parent directory, /// falling back to the system Python if no virtual environment is found. /// @@ -1508,10 +1509,10 @@ pub struct PipShowArgs { /// List packages for the system Python. /// - /// By default, `uv` lists packages in the currently activated virtual environment, or a virtual + /// By default, uv lists packages in the currently activated virtual environment, or a virtual /// environment (`.venv`) located in the current working directory or any parent directory, /// falling back to the system Python if no virtual environment is found. The `--system` option - /// instructs `uv` to use the first Python found in the system `PATH`. + /// instructs uv to use the first Python found in the system `PATH`. /// /// WARNING: `--system` is intended for use in continuous integration (CI) environments and /// should be used with caution. @@ -1546,7 +1547,7 @@ pub struct PipTreeArgs { /// The Python interpreter for which packages should be listed. /// - /// By default, `uv` lists packages in the currently activated virtual environment, or a virtual + /// By default, uv lists packages in the currently activated virtual environment, or a virtual /// environment (`.venv`) located in the current working directory or any parent directory, /// falling back to the system Python if no virtual environment is found. /// @@ -1560,10 +1561,10 @@ pub struct PipTreeArgs { /// List packages for the system Python. /// - /// By default, `uv` lists packages in the currently activated virtual environment, or a virtual + /// By default, uv lists packages in the currently activated virtual environment, or a virtual /// environment (`.venv`) located in the current working directory or any parent directory, /// falling back to the system Python if no virtual environment is found. The `--system` option - /// instructs `uv` to use the first Python found in the system `PATH`. + /// instructs uv to use the first Python found in the system `PATH`. /// /// WARNING: `--system` is intended for use in continuous integration (CI) environments and /// should be used with caution. @@ -1600,8 +1601,8 @@ pub struct VenvArgs { /// Use the system Python to uninstall packages. /// - /// By default, `uv` uninstalls from the virtual environment in the current working directory or - /// any parent directory. The `--system` option instructs `uv` to use the first Python found in + /// By default, uv uninstalls from the virtual environment in the current working directory or + /// any parent directory. The `--system` option instructs uv to use the first Python found in /// the system `PATH`. /// /// WARNING: `--system` is intended for use in continuous integration (CI) environments and @@ -1653,11 +1654,11 @@ pub struct VenvArgs { /// Give the virtual environment access to the system site packages directory. /// - /// Unlike `pip`, when a virtual environment is created with `--system-site-packages`, `uv` will + /// Unlike `pip`, when a virtual environment is created with `--system-site-packages`, uv will /// _not_ take system site packages into account when running commands like `uv pip list` or /// `uv pip install`. The `--system-site-packages` flag will provide the virtual environment /// with access to the system site packages directory at runtime, but it will not affect the - /// behavior of `uv` commands. + /// behavior of uv commands. #[arg(long)] pub system_site_packages: bool, @@ -1666,7 +1667,7 @@ pub struct VenvArgs { /// 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 + /// By default, uv will stop at the first index on which a given package is available, and /// limit resolutions to those present on that first index (`first-match`). This prevents /// "dependency confusion" attacks, whereby an attack can upload a malicious package under the /// same name to a secondary. @@ -1675,7 +1676,7 @@ pub struct VenvArgs { /// Attempt to use `keyring` for authentication for index URLs. /// - /// At present, only `--keyring-provider subprocess` is supported, which configures `uv` to + /// At present, only `--keyring-provider subprocess` is supported, which configures uv to /// use the `keyring` CLI to handle authentication. /// /// Defaults to `disabled`. @@ -1774,7 +1775,7 @@ pub struct RunArgs { /// The Python interpreter to use to build the run environment. /// - /// By default, `uv` uses the virtual environment in the current working directory or any parent + /// By default, uv uses the virtual environment in the current working directory or any parent /// directory, falling back to searching for a Python executable in `PATH`. The `--python` /// option allows you to specify a different interpreter. /// @@ -1835,7 +1836,7 @@ pub struct SyncArgs { /// The Python interpreter to use to build the run environment. /// - /// By default, `uv` uses the virtual environment in the current working directory or any parent + /// By default, uv uses the virtual environment in the current working directory or any parent /// directory, falling back to searching for a Python executable in `PATH`. The `--python` /// option allows you to specify a different interpreter. /// @@ -1862,7 +1863,7 @@ pub struct LockArgs { /// The Python interpreter to use to build the run environment. /// - /// By default, `uv` uses the virtual environment in the current working directory or any parent + /// By default, uv uses the virtual environment in the current working directory or any parent /// directory, falling back to searching for a Python executable in `PATH`. The `--python` /// option allows you to specify a different interpreter. /// @@ -1931,7 +1932,7 @@ pub struct AddArgs { /// The Python interpreter into which packages should be installed. /// - /// By default, `uv` installs into the virtual environment in the current working directory or + /// By default, uv installs into the virtual environment in the current working directory or /// any parent directory. The `--python` option allows you to specify a different interpreter, /// which is intended for use in continuous integration (CI) environments or other automated /// workflows. @@ -1975,7 +1976,7 @@ pub struct RemoveArgs { /// The Python interpreter into which packages should be installed. /// - /// By default, `uv` installs into the virtual environment in the current working directory or + /// By default, uv installs into the virtual environment in the current working directory or /// any parent directory. The `--python` option allows you to specify a different interpreter, /// which is intended for use in continuous integration (CI) environments or other automated /// workflows. @@ -2003,7 +2004,7 @@ pub struct TreeArgs { /// The Python interpreter for which packages should be listed. /// - /// By default, `uv` installs into the virtual environment in the current working directory or + /// By default, uv installs into the virtual environment in the current working directory or /// any parent directory. The `--python` option allows you to specify a different interpreter, /// which is intended for use in continuous integration (CI) environments or other automated /// workflows. @@ -2083,7 +2084,7 @@ pub struct ToolRunArgs { /// The Python interpreter to use to build the run environment. /// - /// By default, `uv` uses the virtual environment in the current working directory or any parent + /// By default, uv uses the virtual environment in the current working directory or any parent /// directory, falling back to searching for a Python executable in `PATH`. The `--python` /// option allows you to specify a different interpreter. /// @@ -2366,7 +2367,7 @@ pub struct InstallerArgs { /// 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 + /// By default, uv will stop at the first index on which a given package is available, and /// limit resolutions to those present on that first index (`first-match`). This prevents /// "dependency confusion" attacks, whereby an attack can upload a malicious package under the /// same name to a secondary. @@ -2375,7 +2376,7 @@ pub struct InstallerArgs { /// Attempt to use `keyring` for authentication for index URLs. /// - /// At present, only `--keyring-provider subprocess` is supported, which configures `uv` to + /// At present, only `--keyring-provider subprocess` is supported, which configures uv to /// use the `keyring` CLI to handle authentication. /// /// Defaults to `disabled`. @@ -2442,7 +2443,7 @@ pub struct ResolverArgs { /// 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 + /// By default, uv will stop at the first index on which a given package is available, and /// limit resolutions to those present on that first index (`first-match`). This prevents /// "dependency confusion" attacks, whereby an attack can upload a malicious package under the /// same name to a secondary. @@ -2451,7 +2452,7 @@ pub struct ResolverArgs { /// Attempt to use `keyring` for authentication for index URLs. /// - /// At present, only `--keyring-provider subprocess` is supported, which configures `uv` to + /// At present, only `--keyring-provider subprocess` is supported, which configures uv to /// use the `keyring` CLI to handle authentication. /// /// Defaults to `disabled`. @@ -2461,13 +2462,13 @@ pub struct ResolverArgs { /// 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`). + /// By default, uv will use the latest compatible version of each package (`highest`). #[arg(long, value_enum, env = "UV_RESOLUTION")] pub resolution: Option, /// The strategy to use when considering pre-release versions. /// - /// By default, `uv` will accept pre-releases for packages that _only_ publish pre-releases, + /// 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`). #[arg(long, value_enum, env = "UV_PRERELEASE")] @@ -2529,7 +2530,7 @@ pub struct ResolverInstallerArgs { /// 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 + /// By default, uv will stop at the first index on which a given package is available, and /// limit resolutions to those present on that first index (`first-match`). This prevents /// "dependency confusion" attacks, whereby an attack can upload a malicious package under the /// same name to a secondary. @@ -2538,7 +2539,7 @@ pub struct ResolverInstallerArgs { /// Attempt to use `keyring` for authentication for index URLs. /// - /// At present, only `--keyring-provider subprocess` is supported, which configures `uv` to + /// At present, only `--keyring-provider subprocess` is supported, which configures uv to /// use the `keyring` CLI to handle authentication. /// /// Defaults to `disabled`. @@ -2548,13 +2549,13 @@ pub struct ResolverInstallerArgs { /// 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`). + /// By default, uv will use the latest compatible version of each package (`highest`). #[arg(long, value_enum, env = "UV_RESOLUTION")] pub resolution: Option, /// The strategy to use when considering pre-release versions. /// - /// By default, `uv` will accept pre-releases for packages that _only_ publish pre-releases, + /// 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`). #[arg(long, value_enum, env = "UV_PRERELEASE")] diff --git a/crates/uv-dev/src/main.rs b/crates/uv-dev/src/main.rs index b7e698d6cd9e..b138bab590de 100644 --- a/crates/uv-dev/src/main.rs +++ b/crates/uv-dev/src/main.rs @@ -124,7 +124,7 @@ async fn main() -> ExitCode { (None, None) }; - // Show `INFO` messages from the `uv` crate, but allow `RUST_LOG` to override. + // Show `INFO` messages from the uv crate, but allow `RUST_LOG` to override. let default_directive = Directive::from_str("uv=info").unwrap(); let filter = EnvFilter::builder() diff --git a/crates/uv-distribution/src/pyproject.rs b/crates/uv-distribution/src/pyproject.rs index 08063a2736a0..974e12e0ca12 100644 --- a/crates/uv-distribution/src/pyproject.rs +++ b/crates/uv-distribution/src/pyproject.rs @@ -78,7 +78,7 @@ pub struct ToolUv { /// The workspace definition for the project, if any. #[option_group] pub workspace: Option, - /// Whether the project is managed by `uv`. If `false`, `uv` will ignore the project when + /// Whether the project is managed by uv. If `false`, uv will ignore the project when /// `uv run` is invoked. #[option( default = r#"true"#, diff --git a/crates/uv-installer/src/compile.rs b/crates/uv-installer/src/compile.rs index 80db5275e712..29bc947a52c4 100644 --- a/crates/uv-installer/src/compile.rs +++ b/crates/uv-installer/src/compile.rs @@ -60,7 +60,7 @@ pub enum CompileError { /// We only compile all files, but we don't update the RECORD, relying on PEP 491: /// > Uninstallers should be smart enough to remove .pyc even if it is not mentioned in RECORD. /// -/// We've confirmed that both `uv` and `pip` (as of 24.0.0) remove the `__pycache__` directory. +/// We've confirmed that both uv and pip (as of 24.0.0) remove the `__pycache__` directory. #[instrument(skip(python_executable))] pub async fn compile_tree( dir: &Path, diff --git a/crates/uv-python/src/virtualenv.rs b/crates/uv-python/src/virtualenv.rs index 461e29bfacef..f4737d9503b2 100644 --- a/crates/uv-python/src/virtualenv.rs +++ b/crates/uv-python/src/virtualenv.rs @@ -24,9 +24,9 @@ pub struct VirtualEnvironment { /// A parsed `pyvenv.cfg` #[derive(Debug, Clone)] pub struct PyVenvConfiguration { - /// If the `virtualenv` package was used to create the virtual environment. + /// If the virtualenv package was used to create the virtual environment. pub(crate) virtualenv: bool, - /// If the `uv` package was used to create the virtual environment. + /// If the uv package was used to create the virtual environment. pub(crate) uv: bool, } @@ -165,7 +165,7 @@ impl PyVenvConfiguration { self.virtualenv } - /// Returns true if the virtual environment was created with the `uv` package. + /// Returns true if the virtual environment was created with the uv package. pub fn is_uv(&self) -> bool { self.uv } diff --git a/crates/uv-settings/src/settings.rs b/crates/uv-settings/src/settings.rs index 4d630e6a544f..aa7b987b2bef 100644 --- a/crates/uv-settings/src/settings.rs +++ b/crates/uv-settings/src/settings.rs @@ -56,12 +56,81 @@ pub struct Options { #[serde(rename_all = "kebab-case")] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] pub struct GlobalOptions { + /// 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. + #[option( + default = "false", + value_type = "bool", + example = r#" + native-tls = true + "# + )] pub native_tls: Option, + /// Disable network access, relying only on locally cached data and locally available files. + #[option( + default = "false", + value_type = "bool", + example = r#" + offline = true + "# + )] pub offline: Option, + /// Avoid reading from or writing to the cache, instead using a temporary directory for the + /// duration of the operation. + #[option( + default = "false", + value_type = "bool", + example = r#" + no-cache = true + "# + )] pub no_cache: Option, + /// Path to the cache directory. + /// + /// Defaults to `$HOME/Library/Caches/uv` on macOS, `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv` on + /// Linux, and `{FOLDERID_LocalAppData}\uv\cache` on Windows. + #[option( + default = "None", + value_type = "str", + example = r#" + cache-dir = "./.uv_cache" + "# + )] pub cache_dir: Option, + /// Whether to enable experimental, preview features. + #[option( + default = "false", + value_type = "bool", + example = r#" + preview = true + "# + )] pub preview: Option, + /// Whether to prefer using Python installations that are already present on the system, or + /// those that are downloaded and installed by uv. + #[option( + default = "\"installed\"", + value_type = "str", + example = r#" + python-preference = "managed" + "# + )] pub python_preference: Option, + /// Whether to automatically download Python when required. + #[option( + default = "\"automatic\"", + value_type = "str", + example = r#" + python-fetch = \"automatic\" + "# + )] pub python_fetch: Option, } @@ -182,7 +251,7 @@ pub struct ResolverInstallerOptions { pub find_links: Option>, /// 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 + /// By default, uv will stop at the first index on which a given package is available, and /// limit resolutions to those present on that first index (`first-match`). This prevents /// "dependency confusion" attacks, whereby an attack can upload a malicious package under the /// same name to a secondary. @@ -202,7 +271,7 @@ pub struct ResolverInstallerOptions { pub index_strategy: Option, /// Attempt to use `keyring` for authentication for index URLs. /// - /// At present, only `--keyring-provider subprocess` is supported, which configures `uv` to + /// At present, only `--keyring-provider subprocess` is supported, which configures uv to /// use the `keyring` CLI to handle authentication. #[option( default = "\"disabled\"", @@ -215,7 +284,7 @@ pub struct ResolverInstallerOptions { /// 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`). + /// By default, uv will use the latest compatible version of each package (`highest`). #[option( default = "\"highest\"", value_type = "str", @@ -226,7 +295,7 @@ pub struct ResolverInstallerOptions { pub resolution: Option, /// The strategy to use when considering pre-release versions. /// - /// By default, `uv` will accept pre-releases for packages that _only_ publish pre-releases, + /// 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`). #[option( diff --git a/crates/uv-types/src/lib.rs b/crates/uv-types/src/lib.rs index df0b6c4a890c..ea28c0f03894 100644 --- a/crates/uv-types/src/lib.rs +++ b/crates/uv-types/src/lib.rs @@ -1,4 +1,4 @@ -//! Fundamental types shared across `uv` crates. +//! Fundamental types shared across uv crates. pub use builds::*; pub use downloads::*; pub use hash::*; diff --git a/crates/uv/src/commands/pip/compile.rs b/crates/uv/src/commands/pip/compile.rs index b0dc0d977009..251f483b1a81 100644 --- a/crates/uv/src/commands/pip/compile.rs +++ b/crates/uv/src/commands/pip/compile.rs @@ -491,7 +491,7 @@ pub(crate) async fn pip_compile( Ok(ExitStatus::Success) } -/// Format the `uv` command used to generate the output file. +/// Format the uv command used to generate the output file. #[allow(clippy::fn_params_excessive_bools)] fn cmd( include_index_url: bool, diff --git a/crates/uv/src/commands/self_update.rs b/crates/uv/src/commands/self_update.rs index be3b5050d0be..34a80dc1f83a 100644 --- a/crates/uv/src/commands/self_update.rs +++ b/crates/uv/src/commands/self_update.rs @@ -10,24 +10,24 @@ use uv_client::WrappedReqwestError; use crate::commands::ExitStatus; use crate::printer::Printer; -/// Attempt to update the `uv` binary. +/// Attempt to update the uv binary. pub(crate) async fn self_update(printer: Printer) -> Result { let mut updater = AxoUpdater::new_for("uv"); updater.disable_installer_output(); // Load the "install receipt" for the current binary. If the receipt is not found, then - // `uv` was likely installed via a package manager. + // uv was likely installed via a package manager. let Ok(updater) = updater.load_receipt() else { - debug!("no receipt found; assuming `uv` was installed via a package manager"); + debug!("no receipt found; assuming uv was installed via a package manager"); writeln!( printer.stderr(), "{}", format_args!( concat!( - "{}{} Self-update is only available for `uv` binaries installed via the standalone installation scripts.", + "{}{} Self-update is only available for uv binaries installed via the standalone installation scripts.", "\n", "\n", - "If you installed `uv` with `pip`, `brew`, or another package manager, update `uv` with `pip install --upgrade`, `brew upgrade`, or similar." + "If you installed uv with pip, brew, or another package manager, update uv with `pip install --upgrade`, `brew upgrade`, or similar." ), "warning".yellow().bold(), ":".bold() @@ -37,21 +37,21 @@ pub(crate) async fn self_update(printer: Printer) -> Result { }; // Ensure the receipt is for the current binary. If it's not, then the user likely has multiple - // `uv` binaries installed, and the current binary was _not_ installed via the standalone + // uv binaries installed, and the current binary was _not_ installed via the standalone // installation scripts. if !updater.check_receipt_is_for_this_executable()? { debug!( - "receipt is not for this executable; assuming `uv` was installed via a package manager" + "receipt is not for this executable; assuming uv was installed via a package manager" ); writeln!( printer.stderr(), "{}", format_args!( concat!( - "{}{} Self-update is only available for `uv` binaries installed via the standalone installation scripts.", + "{}{} Self-update is only available for uv binaries installed via the standalone installation scripts.", "\n", "\n", - "If you installed `uv` with `pip`, `brew`, or another package manager, update `uv` with `pip install --upgrade`, `brew upgrade`, or similar." + "If you installed uv with pip, brew, or another package manager, update uv with `pip install --upgrade`, `brew upgrade`, or similar." ), "warning".yellow().bold(), ":".bold() @@ -71,14 +71,14 @@ pub(crate) async fn self_update(printer: Printer) -> Result { )?; // Run the updater. This involves a network request, since we need to determine the latest - // available version of `uv`. + // available version of uv. match updater.run().await { Ok(Some(result)) => { writeln!( printer.stderr(), "{}", format_args!( - "{}{} Upgraded `uv` to {}! {}", + "{}{} Upgraded uv to {}! {}", "success".green().bold(), ":".bold(), format!("v{}", result.new_version).bold().white(), @@ -95,7 +95,7 @@ pub(crate) async fn self_update(printer: Printer) -> Result { printer.stderr(), "{}", format_args!( - "{}{} You're on the latest version of `uv` ({}).", + "{}{} You're on the latest version of uv ({}).", "success".green().bold(), ":".bold(), format!("v{}", env!("CARGO_PKG_VERSION")).bold().white() diff --git a/crates/uv/src/commands/tool/run.rs b/crates/uv/src/commands/tool/run.rs index 5cfb709639b4..0170d71ce262 100644 --- a/crates/uv/src/commands/tool/run.rs +++ b/crates/uv/src/commands/tool/run.rs @@ -411,7 +411,7 @@ fn parse_target(target: &OsString) -> Result<(Cow, Cow)> { return Err(anyhow::anyhow!("Tool command could not be parsed as UTF-8 string. Use `--from` to specify the package name.")); }; - // e.g. `uv`, no special handling + // e.g. uv, no special handling let Some((name, version)) = target_str.split_once('@') else { return Ok((Cow::Borrowed(target), Cow::Borrowed(target_str))); }; diff --git a/crates/uv/src/lib.rs b/crates/uv/src/lib.rs index 7b96cb5db964..e94e23e26996 100644 --- a/crates/uv/src/lib.rs +++ b/crates/uv/src/lib.rs @@ -987,7 +987,7 @@ async fn run_project( /// The main entry point for a uv invocation. /// /// WARNING: This entry point is not recommended for external consumption, the -/// `uv` binary interface is the official public API. When using this entry +/// uv binary interface is the official public API. When using this entry /// point, uv assumes it is running in a process it controls and that the /// entire process lifetime is managed by uv. Unexpected behavior may be /// encountered if this entry pointis called multiple times in a single process. diff --git a/crates/uv/src/settings.rs b/crates/uv/src/settings.rs index b61186d64a13..12e47180c8a8 100644 --- a/crates/uv/src/settings.rs +++ b/crates/uv/src/settings.rs @@ -1300,7 +1300,7 @@ impl VenvSettings { } } -/// The resolved settings to use for an invocation of the `uv` CLI when installing dependencies. +/// The resolved settings to use for an invocation of the uv CLI when installing dependencies. /// /// Combines the `[tool.uv]` persistent configuration with the command-line arguments /// ([`InstallerArgs`], represented as [`InstallerOptions`]). @@ -1317,7 +1317,7 @@ pub(crate) struct InstallerSettingsRef<'a> { pub(crate) build_options: &'a BuildOptions, } -/// The resolved settings to use for an invocation of the `uv` CLI when resolving dependencies. +/// The resolved settings to use for an invocation of the uv CLI when resolving dependencies. /// /// Combines the `[tool.uv]` persistent configuration with the command-line arguments /// ([`ResolverArgs`], represented as [`ResolverOptions`]). @@ -1446,10 +1446,10 @@ impl ResolverSettings { } } -/// The resolved settings to use for an invocation of the `uv` CLI with both resolver and installer +/// The resolved settings to use for an invocation of the uv CLI with both resolver and installer /// capabilities. /// -/// Represents the shared settings that are used across all `uv` commands outside the `pip` API. +/// Represents the shared settings that are used across all uv commands outside the `pip` API. /// Analogous to the settings contained in the `[tool.uv]` table, combined with [`ResolverInstallerArgs`]. #[allow(clippy::struct_excessive_bools)] #[derive(Debug, Clone, Default)] diff --git a/crates/uv/tests/common/mod.rs b/crates/uv/tests/common/mod.rs index d3056a89430e..7559b8ddc625 100644 --- a/crates/uv/tests/common/mod.rs +++ b/crates/uv/tests/common/mod.rs @@ -313,7 +313,7 @@ impl TestContext { } } - /// Create a `uv` command for testing. + /// Create a uv command for testing. pub fn command(&self) -> Command { let mut command = Command::new(get_bin()); self.add_shared_args(&mut command); diff --git a/crates/uv/tests/help.rs b/crates/uv/tests/help.rs index 270974caa401..2d4c5cd0f10e 100644 --- a/crates/uv/tests/help.rs +++ b/crates/uv/tests/help.rs @@ -37,8 +37,9 @@ fn help() { --offline Disable network access, relying only on locally cached data and locally available files --python-preference - Whether to prefer using Python from uv or on the system [possible values: only-managed, - installed, managed, system, only-system] + Whether to prefer using Python installations that are already present on the system, or + those that are downloaded and installed by uv [possible values: only-managed, installed, + managed, system, only-system] --python-fetch Whether to automatically download Python when required [possible values: automatic, manual] @@ -46,7 +47,8 @@ fn help() { Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any parent directories -n, --no-cache - Avoid reading from or writing to the cache [env: UV_NO_CACHE=] + Avoid reading from or writing to the cache, instead using a temporary directory for the + duration of the operation [env: UV_NO_CACHE=] --cache-dir [CACHE_DIR] Path to the cache directory [env: UV_CACHE_DIR=] --config-file @@ -96,8 +98,9 @@ fn help_flag() { --offline Disable network access, relying only on locally cached data and locally available files --python-preference - Whether to prefer using Python from uv or on the system [possible values: only-managed, - installed, managed, system, only-system] + Whether to prefer using Python installations that are already present on the system, or + those that are downloaded and installed by uv [possible values: only-managed, installed, + managed, system, only-system] --python-fetch Whether to automatically download Python when required [possible values: automatic, manual] @@ -105,7 +108,8 @@ fn help_flag() { Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any parent directories -n, --no-cache - Avoid reading from or writing to the cache [env: UV_NO_CACHE=] + Avoid reading from or writing to the cache, instead using a temporary directory for the + duration of the operation [env: UV_NO_CACHE=] --cache-dir [CACHE_DIR] Path to the cache directory [env: UV_CACHE_DIR=] --config-file @@ -154,8 +158,9 @@ fn help_short_flag() { --offline Disable network access, relying only on locally cached data and locally available files --python-preference - Whether to prefer using Python from uv or on the system [possible values: only-managed, - installed, managed, system, only-system] + Whether to prefer using Python installations that are already present on the system, or + those that are downloaded and installed by uv [possible values: only-managed, installed, + managed, system, only-system] --python-fetch Whether to automatically download Python when required [possible values: automatic, manual] @@ -163,7 +168,8 @@ fn help_short_flag() { Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any parent directories -n, --no-cache - Avoid reading from or writing to the cache [env: UV_NO_CACHE=] + Avoid reading from or writing to the cache, instead using a temporary directory for the + duration of the operation [env: UV_NO_CACHE=] --cache-dir [CACHE_DIR] Path to the cache directory [env: UV_CACHE_DIR=] --config-file @@ -223,8 +229,8 @@ fn help_subcommand() { --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` + 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, @@ -237,7 +243,8 @@ fn help_subcommand() { Disable network access, relying only on locally cached data and locally available files --python-preference - Whether to prefer using Python from uv or on the system + Whether to prefer using Python installations that are already present on the system, or + those that are downloaded and installed by uv Possible values: - only-managed: Only use managed Python installations; never use system Python @@ -263,7 +270,8 @@ fn help_subcommand() { parent directories -n, --no-cache - Avoid reading from or writing to the cache + Avoid reading from or writing to the cache, instead using a temporary directory for the + duration of the operation [env: UV_NO_CACHE=] @@ -340,8 +348,8 @@ fn help_subsubcommand() { --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` + 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, @@ -354,7 +362,8 @@ fn help_subsubcommand() { Disable network access, relying only on locally cached data and locally available files --python-preference - Whether to prefer using Python from uv or on the system + Whether to prefer using Python installations that are already present on the system, or + those that are downloaded and installed by uv Possible values: - only-managed: Only use managed Python installations; never use system Python @@ -380,7 +389,8 @@ fn help_subsubcommand() { parent directories -n, --no-cache - Avoid reading from or writing to the cache + Avoid reading from or writing to the cache, instead using a temporary directory for the + duration of the operation [env: UV_NO_CACHE=] @@ -441,8 +451,9 @@ fn help_flag_subcommand() { --offline Disable network access, relying only on locally cached data and locally available files --python-preference - Whether to prefer using Python from uv or on the system [possible values: only-managed, - installed, managed, system, only-system] + Whether to prefer using Python installations that are already present on the system, or + those that are downloaded and installed by uv [possible values: only-managed, installed, + managed, system, only-system] --python-fetch Whether to automatically download Python when required [possible values: automatic, manual] @@ -450,7 +461,8 @@ fn help_flag_subcommand() { Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any parent directories -n, --no-cache - Avoid reading from or writing to the cache [env: UV_NO_CACHE=] + Avoid reading from or writing to the cache, instead using a temporary directory for the + duration of the operation [env: UV_NO_CACHE=] --cache-dir [CACHE_DIR] Path to the cache directory [env: UV_CACHE_DIR=] --config-file @@ -496,8 +508,9 @@ fn help_flag_subsubcommand() { --offline Disable network access, relying only on locally cached data and locally available files --python-preference - Whether to prefer using Python from uv or on the system [possible values: only-managed, - installed, managed, system, only-system] + Whether to prefer using Python installations that are already present on the system, or + those that are downloaded and installed by uv [possible values: only-managed, installed, + managed, system, only-system] --python-fetch Whether to automatically download Python when required [possible values: automatic, manual] @@ -505,7 +518,8 @@ fn help_flag_subsubcommand() { Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any parent directories -n, --no-cache - Avoid reading from or writing to the cache [env: UV_NO_CACHE=] + Avoid reading from or writing to the cache, instead using a temporary directory for the + duration of the operation [env: UV_NO_CACHE=] --cache-dir [CACHE_DIR] Path to the cache directory [env: UV_CACHE_DIR=] --config-file @@ -608,8 +622,9 @@ fn help_with_global_option() { --offline Disable network access, relying only on locally cached data and locally available files --python-preference - Whether to prefer using Python from uv or on the system [possible values: only-managed, - installed, managed, system, only-system] + Whether to prefer using Python installations that are already present on the system, or + those that are downloaded and installed by uv [possible values: only-managed, installed, + managed, system, only-system] --python-fetch Whether to automatically download Python when required [possible values: automatic, manual] @@ -617,7 +632,8 @@ fn help_with_global_option() { Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any parent directories -n, --no-cache - Avoid reading from or writing to the cache [env: UV_NO_CACHE=] + Avoid reading from or writing to the cache, instead using a temporary directory for the + duration of the operation [env: UV_NO_CACHE=] --cache-dir [CACHE_DIR] Path to the cache directory [env: UV_CACHE_DIR=] --config-file @@ -700,8 +716,9 @@ fn test_with_no_pager() { --offline Disable network access, relying only on locally cached data and locally available files --python-preference - Whether to prefer using Python from uv or on the system [possible values: only-managed, - installed, managed, system, only-system] + Whether to prefer using Python installations that are already present on the system, or + those that are downloaded and installed by uv [possible values: only-managed, installed, + managed, system, only-system] --python-fetch Whether to automatically download Python when required [possible values: automatic, manual] @@ -709,7 +726,8 @@ fn test_with_no_pager() { Avoid discovering a `pyproject.toml` or `uv.toml` file in the current directory or any parent directories -n, --no-cache - Avoid reading from or writing to the cache [env: UV_NO_CACHE=] + Avoid reading from or writing to the cache, instead using a temporary directory for the + duration of the operation [env: UV_NO_CACHE=] --cache-dir [CACHE_DIR] Path to the cache directory [env: UV_CACHE_DIR=] --config-file diff --git a/crates/uv/tests/pip_install.rs b/crates/uv/tests/pip_install.rs index 14f2f829c85d..55b99efb5607 100644 --- a/crates/uv/tests/pip_install.rs +++ b/crates/uv/tests/pip_install.rs @@ -1282,14 +1282,14 @@ fn install_no_index_version() { /// Install a package via --extra-index-url. /// -/// This is a regression test where previously `uv` would consult test.pypi.org -/// first, and if the package was found there, `uv` would not look at any other +/// This is a regression test where previously uv would consult test.pypi.org +/// first, and if the package was found there, uv would not look at any other /// indexes. We fixed this by flipping the priority order of indexes so that /// test.pypi.org becomes the fallback (in this example) and the extra indexes /// (regular PyPI) are checked first. /// /// (Neither approach matches `pip`'s behavior, which considers versions of -/// each package from all indexes. `uv` stops at the first index it finds a +/// each package from all indexes. uv stops at the first index it finds a /// package in.) /// /// Ref: @@ -1308,7 +1308,7 @@ fn install_extra_index_url_has_priority() { // `black==24.2.0` is on pypi.org and NOT test.pypi.org. So // this would previously check for `black` on test.pypi.org, // find it, but then not find a compatible version. After - // the fix, `uv` will check pypi.org first since it is given + // the fix, uv will check pypi.org first since it is given // priority via --extra-index-url. .arg("black==24.2.0") .arg("--no-deps") @@ -3520,7 +3520,7 @@ fn respect_no_build_isolation_env_var() -> Result<()> { Ok(()) } -/// This tests that `uv` can read UTF-16LE encoded requirements.txt files. +/// This tests that uv can read UTF-16LE encoded requirements.txt files. /// /// Ref: #[test] @@ -3547,7 +3547,7 @@ fn install_utf16le_requirements() -> Result<()> { Ok(()) } -/// This tests that `uv` can read UTF-16BE encoded requirements.txt files. +/// This tests that uv can read UTF-16BE encoded requirements.txt files. /// /// Ref: #[test] diff --git a/docs/settings.md b/docs/settings.md index 8f95adec9296..61572bda580c 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -1,4 +1,32 @@ ## Global +#### [`cache-dir`](#cache-dir) {: #cache-dir } + +Path to the cache directory. + +Defaults to `$HOME/Library/Caches/uv` on macOS, `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv` on +Linux, and `{FOLDERID_LocalAppData}\uv\cache` on Windows. + +**Default value**: `None` + +**Type**: `str` + +**Example usage**: + +=== "pyproject.toml" + + ```toml + [tool.uv] + cache-dir = "./.uv_cache" + ``` +=== "uv.toml" + + ```toml + + cache-dir = "./.uv_cache" + ``` + +--- + #### [`compile-bytecode`](#compile-bytecode) {: #compile-bytecode } Compile Python files to bytecode after installation. @@ -155,7 +183,7 @@ formats described above. 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 +By default, uv will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (`first-match`). This prevents "dependency confusion" attacks, whereby an attack can upload a malicious package under the same name to a secondary. @@ -222,7 +250,7 @@ The index provided by this setting is given lower priority than any indexes spec Attempt to use `keyring` for authentication for index URLs. -At present, only `--keyring-provider subprocess` is supported, which configures `uv` to +At present, only `--keyring-provider subprocess` is supported, which configures uv to use the `keyring` CLI to handle authentication. **Default value**: `"disabled"` @@ -276,7 +304,7 @@ Windows. #### [`managed`](#managed) {: #managed } -Whether the project is managed by `uv`. If `false`, `uv` will ignore the project when +Whether the project is managed by uv. If `false`, uv will ignore the project when `uv run` is invoked. **Default value**: `true` @@ -300,6 +328,39 @@ Whether the project is managed by `uv`. If `false`, `uv` will ignore the project --- +#### [`native-tls`](#native-tls) {: #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. + +**Default value**: `false` + +**Type**: `bool` + +**Example usage**: + +=== "pyproject.toml" + + ```toml + [tool.uv] + native-tls = true + ``` +=== "uv.toml" + + ```toml + + native-tls = true + ``` + +--- + #### [`no-binary`](#no-binary) {: #no-binary } Don't install pre-built wheels. @@ -407,6 +468,32 @@ Don't build source distributions for a specific package. --- +#### [`no-cache`](#no-cache) {: #no-cache } + +Avoid reading from or writing to the cache, instead using a temporary directory for the +duration of the operation. + +**Default value**: `false` + +**Type**: `bool` + +**Example usage**: + +=== "pyproject.toml" + + ```toml + [tool.uv] + no-cache = true + ``` +=== "uv.toml" + + ```toml + + no-cache = true + ``` + +--- + #### [`no-index`](#no-index) {: #no-index } Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and @@ -433,11 +520,36 @@ those provided via `--find-links`. --- +#### [`offline`](#offline) {: #offline } + +Disable network access, relying only on locally cached data and locally available files. + +**Default value**: `false` + +**Type**: `bool` + +**Example usage**: + +=== "pyproject.toml" + + ```toml + [tool.uv] + offline = true + ``` +=== "uv.toml" + + ```toml + + offline = true + ``` + +--- + #### [`prerelease`](#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, +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`). @@ -462,6 +574,82 @@ declared specifiers (`if-necessary-or-explicit`). --- +#### [`preview`](#preview) {: #preview } + +Whether to enable experimental, preview features. + +**Default value**: `false` + +**Type**: `bool` + +**Example usage**: + +=== "pyproject.toml" + + ```toml + [tool.uv] + preview = true + ``` +=== "uv.toml" + + ```toml + + preview = true + ``` + +--- + +#### [`python-fetch`](#python-fetch) {: #python-fetch } + +Whether to automatically download Python when required. + +**Default value**: `"automatic"` + +**Type**: `str` + +**Example usage**: + +=== "pyproject.toml" + + ```toml + [tool.uv] + python-fetch = \"automatic\" + ``` +=== "uv.toml" + + ```toml + + python-fetch = \"automatic\" + ``` + +--- + +#### [`python-preference`](#python-preference) {: #python-preference } + +Whether to prefer using Python installations that are already present on the system, or +those that are downloaded and installed by uv. + +**Default value**: `"installed"` + +**Type**: `str` + +**Example usage**: + +=== "pyproject.toml" + + ```toml + [tool.uv] + python-preference = "managed" + ``` +=== "uv.toml" + + ```toml + + python-preference = "managed" + ``` + +--- + #### [`reinstall`](#reinstall) {: #reinstall } Reinstall all packages, regardless of whether they're already installed. @@ -517,7 +705,7 @@ Reinstall a specific package, regardless of whether it's already installed. 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`). +By default, uv will use the latest compatible version of each package (`highest`). **Default value**: `"highest"` diff --git a/uv.schema.json b/uv.schema.json index 522b4a7bb3c3..f1f2e570864b 100644 --- a/uv.schema.json +++ b/uv.schema.json @@ -5,6 +5,7 @@ "type": "object", "properties": { "cache-dir": { + "description": "Path to the cache directory.\n\nDefaults to `$HOME/Library/Caches/uv` on macOS, `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv` on Linux, and `{FOLDERID_LocalAppData}\\uv\\cache` on Windows.", "type": [ "string", "null" @@ -70,7 +71,7 @@ } }, "index-strategy": { - "description": "The strategy to use when resolving against multiple index URLs.\n\nBy default, `uv` will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (`first-match`). This prevents \"dependency confusion\" attacks, whereby an attack can upload a malicious package under the same name to a secondary.\n\nPossible values:\n\n- `\"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.", + "description": "The strategy to use when resolving against multiple index URLs.\n\nBy default, uv will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (`first-match`). This prevents \"dependency confusion\" attacks, whereby an attack can upload a malicious package under the same name to a secondary.\n\nPossible values:\n\n- `\"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.", "anyOf": [ { "$ref": "#/definitions/IndexStrategy" @@ -92,7 +93,7 @@ ] }, "keyring-provider": { - "description": "Attempt to use `keyring` for authentication for index URLs.\n\nAt present, only `--keyring-provider subprocess` is supported, which configures `uv` to use the `keyring` CLI to handle authentication.", + "description": "Attempt to use `keyring` for authentication for index URLs.\n\nAt present, only `--keyring-provider subprocess` is supported, which configures uv to use the `keyring` CLI to handle authentication.", "anyOf": [ { "$ref": "#/definitions/KeyringProviderType" @@ -114,13 +115,14 @@ ] }, "managed": { - "description": "Whether the project is managed by `uv`. If `false`, `uv` will ignore the project when `uv run` is invoked.", + "description": "Whether the project is managed by uv. If `false`, uv will ignore the project when `uv run` is invoked.", "type": [ "boolean", "null" ] }, "native-tls": { + "description": "Whether to load TLS certificates from the platform's native certificate store.\n\nBy 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).\n\nHowever, 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.", "type": [ "boolean", "null" @@ -161,6 +163,7 @@ } }, "no-cache": { + "description": "Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation.", "type": [ "boolean", "null" @@ -174,6 +177,7 @@ ] }, "offline": { + "description": "Disable network access, relying only on locally cached data and locally available files.", "type": [ "boolean", "null" @@ -200,7 +204,7 @@ ] }, "prerelease": { - "description": "The strategy to use when considering pre-release versions.\n\nBy 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`).", + "description": "The strategy to use when considering pre-release versions.\n\nBy 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`).", "anyOf": [ { "$ref": "#/definitions/PreReleaseMode" @@ -211,12 +215,14 @@ ] }, "preview": { + "description": "Whether to enable experimental, preview features.", "type": [ "boolean", "null" ] }, "python-fetch": { + "description": "Whether to automatically download Python when required.", "anyOf": [ { "$ref": "#/definitions/PythonFetch" @@ -227,6 +233,7 @@ ] }, "python-preference": { + "description": "Whether to prefer using Python installations that are already present on the system, or those that are downloaded and installed by uv.", "anyOf": [ { "$ref": "#/definitions/PythonPreference" @@ -254,7 +261,7 @@ } }, "resolution": { - "description": "The strategy to use when selecting between the different compatible versions for a given package requirement.\n\nBy default, `uv` will use the latest compatible version of each package (`highest`).", + "description": "The strategy to use when selecting between the different compatible versions for a given package requirement.\n\nBy default, uv will use the latest compatible version of each package (`highest`).", "anyOf": [ { "$ref": "#/definitions/ResolutionMode"