mirror of
https://github.com/astral-sh/uv.git
synced 2025-08-03 10:33:49 +00:00
Add reference documentation for resolver settings (#5122)
## Summary First part of https://github.com/astral-sh/uv/issues/5093. Remaining: - Global settings - `pip`-specific settings (some will be copied-over from here) - Auto-generating the "Possible values" for enums
This commit is contained in:
Charlie Marsh
GitHub
parent
abb6ac5127
commit
616a61a244
5 changed files with 808 additions and 36 deletions
|
|
@ -621,9 +621,9 @@ pub struct PipCompileArgs {
|
|||
|
||||
/// Don't build source distributions.
|
||||
///
|
||||
/// When enabled, resolving will not run arbitrary code. The cached wheels of already-built
|
||||
/// source distributions will be reused, but operations that require building distributions will
|
||||
/// exit with an error.
|
||||
/// When enabled, resolving will not run arbitrary Python code. The cached wheels of
|
||||
/// already-built source distributions will be reused, but operations that require building
|
||||
/// distributions will exit with an error.
|
||||
///
|
||||
/// Alias for `--only-binary :all:`.
|
||||
#[arg(
|
||||
|
|
@ -645,8 +645,8 @@ pub struct PipCompileArgs {
|
|||
|
||||
/// Don't install pre-built wheels.
|
||||
///
|
||||
/// The given packages will be installed from a source distribution. The resolver
|
||||
/// will still use pre-built wheels for metadata.
|
||||
/// The given packages will be built and installed from source. The resolver will still use
|
||||
/// pre-built wheels to extract package metadata, if available.
|
||||
///
|
||||
/// Multiple packages may be provided. Disable binaries for all packages with `:all:`.
|
||||
/// Clear previously specified packages with `:none:`.
|
||||
|
|
@ -884,9 +884,9 @@ pub struct PipSyncArgs {
|
|||
|
||||
/// Don't build source distributions.
|
||||
///
|
||||
/// When enabled, resolving will not run arbitrary code. The cached wheels of already-built
|
||||
/// source distributions will be reused, but operations that require building distributions will
|
||||
/// exit with an error.
|
||||
/// When enabled, resolving will not run arbitrary Python code. The cached wheels of
|
||||
/// already-built source distributions will be reused, but operations that require building
|
||||
/// distributions will exit with an error.
|
||||
///
|
||||
/// Alias for `--only-binary :all:`.
|
||||
#[arg(
|
||||
|
|
@ -908,8 +908,8 @@ pub struct PipSyncArgs {
|
|||
|
||||
/// Don't install pre-built wheels.
|
||||
///
|
||||
/// The given packages will be installed from a source distribution. The resolver
|
||||
/// will still use pre-built wheels for metadata.
|
||||
/// The given packages will be built and installed from source. The resolver will still use
|
||||
/// pre-built wheels to extract package metadata, if available.
|
||||
///
|
||||
/// Multiple packages may be provided. Disable binaries for all packages with `:all:`.
|
||||
/// Clear previously specified packages with `:none:`.
|
||||
|
|
@ -1156,9 +1156,9 @@ pub struct PipInstallArgs {
|
|||
|
||||
/// Don't build source distributions.
|
||||
///
|
||||
/// When enabled, resolving will not run arbitrary code. The cached wheels of already-built
|
||||
/// source distributions will be reused, but operations that require building distributions will
|
||||
/// exit with an error.
|
||||
/// When enabled, resolving will not run arbitrary Python code. The cached wheels of
|
||||
/// already-built source distributions will be reused, but operations that require building
|
||||
/// distributions will exit with an error.
|
||||
///
|
||||
/// Alias for `--only-binary :all:`.
|
||||
#[arg(
|
||||
|
|
@ -1180,8 +1180,8 @@ pub struct PipInstallArgs {
|
|||
|
||||
/// Don't install pre-built wheels.
|
||||
///
|
||||
/// The given packages will be installed from a source distribution. The resolver
|
||||
/// will still use pre-built wheels for metadata.
|
||||
/// The given packages will be built and installed from source. The resolver will still use
|
||||
/// pre-built wheels to extract package metadata, if available.
|
||||
///
|
||||
/// Multiple packages may be provided. Disable binaries for all packages with `:all:`.
|
||||
/// Clear previously specified packages with `:none:`.
|
||||
|
|
@ -1878,7 +1878,7 @@ pub struct LockArgs {
|
|||
#[derive(Args)]
|
||||
#[allow(clippy::struct_excessive_bools)]
|
||||
pub struct AddArgs {
|
||||
/// The packages to add, as PEP 508 requirements (e.g., `flask==2.2.3`).
|
||||
/// The packages to add, as PEP 508 requirements (e.g., `ruff==0.5.0`).
|
||||
#[arg(required = true)]
|
||||
pub requirements: Vec<String>,
|
||||
|
||||
|
|
@ -1948,7 +1948,7 @@ pub struct AddArgs {
|
|||
#[derive(Args)]
|
||||
#[allow(clippy::struct_excessive_bools)]
|
||||
pub struct RemoveArgs {
|
||||
/// The names of the packages to remove (e.g., `flask`).
|
||||
/// The names of the packages to remove (e.g., `ruff`).
|
||||
#[arg(required = true)]
|
||||
pub requirements: Vec<PackageName>,
|
||||
|
||||
|
|
@ -2270,23 +2270,25 @@ pub struct IndexArgs {
|
|||
/// Accepts either a repository compliant with PEP 503 (the simple repository API), or a local
|
||||
/// directory laid out in the same format.
|
||||
///
|
||||
/// All indexes given via this flag take priority over the index
|
||||
/// in `--index-url` (which defaults to PyPI). And when multiple
|
||||
/// `--extra-index-url` flags are given, earlier values take priority.
|
||||
/// All indexes provided via this flag take priority over the index specified by
|
||||
/// `--index-url` (which defaults to PyPI). When multiple `--extra-index-url` flags are
|
||||
/// provided, earlier values take priority.
|
||||
#[arg(long, env = "UV_EXTRA_INDEX_URL", value_delimiter = ' ', value_parser = parse_index_url)]
|
||||
pub extra_index_url: Option<Vec<Maybe<IndexUrl>>>,
|
||||
|
||||
/// Locations to search for candidate distributions, beyond those found in the indexes.
|
||||
/// Locations to search for candidate distributions, in addition to those found in the registry
|
||||
/// indexes.
|
||||
///
|
||||
/// If a path, the target must be a directory that contains package as wheel files (`.whl`) or
|
||||
/// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or
|
||||
/// source distributions (`.tar.gz` or `.zip`) at the top level.
|
||||
///
|
||||
/// If a URL, the page must contain a flat list of links to package files.
|
||||
/// If a URL, the page must contain a flat list of links to package files adhering to the
|
||||
/// formats described above.
|
||||
#[arg(long, short)]
|
||||
pub find_links: Option<Vec<FlatIndexLocation>>,
|
||||
|
||||
/// Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those
|
||||
/// discovered via `--find-links`.
|
||||
/// provided via `--find-links`.
|
||||
#[arg(long)]
|
||||
pub no_index: bool,
|
||||
}
|
||||
|
|
@ -2316,9 +2318,9 @@ pub struct RefreshArgs {
|
|||
pub struct BuildArgs {
|
||||
/// Don't build source distributions.
|
||||
///
|
||||
/// When enabled, resolving will not run arbitrary code. The cached wheels of already-built
|
||||
/// source distributions will be reused, but operations that require building distributions will
|
||||
/// exit with an error.
|
||||
/// When enabled, resolving will not run arbitrary Python code. The cached wheels of
|
||||
/// already-built source distributions will be reused, but operations that require building
|
||||
/// distributions will exit with an error.
|
||||
#[arg(long, overrides_with("build"))]
|
||||
pub no_build: bool,
|
||||
|
||||
|
|
@ -2331,8 +2333,8 @@ pub struct BuildArgs {
|
|||
|
||||
/// Don't install pre-built wheels.
|
||||
///
|
||||
/// The given packages will be installed from a source distribution. The resolver
|
||||
/// will still use pre-built wheels for metadata.
|
||||
/// The given packages will be built and installed from source. The resolver will still use
|
||||
/// pre-built wheels to extract package metadata, if available.
|
||||
#[arg(long, overrides_with("binary"))]
|
||||
pub no_binary: bool,
|
||||
|
||||
|
|
|
|||
|
|
@ -92,7 +92,7 @@ pub struct ToolUv {
|
|||
feature = "schemars",
|
||||
schemars(
|
||||
with = "Option<Vec<String>>",
|
||||
description = "PEP 508-style requirements, e.g., `flask==3.0.0`, or `black @ https://...`."
|
||||
description = "PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`."
|
||||
)
|
||||
)]
|
||||
pub dev_dependencies: Option<Vec<pep508_rs::Requirement<VerbatimParsedUrl>>>,
|
||||
|
|
@ -100,7 +100,7 @@ pub struct ToolUv {
|
|||
feature = "schemars",
|
||||
schemars(
|
||||
with = "Option<Vec<String>>",
|
||||
description = "PEP 508 style requirements, e.g. `flask==3.0.0`, or `black @ https://...`."
|
||||
description = "PEP 508 style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`."
|
||||
)
|
||||
)]
|
||||
pub override_dependencies: Option<Vec<pep508_rs::Requirement<VerbatimParsedUrl>>>,
|
||||
|
|
|
|||
|
|
@ -44,7 +44,7 @@ pub struct Options {
|
|||
feature = "schemars",
|
||||
schemars(
|
||||
with = "Option<Vec<String>>",
|
||||
description = "PEP 508 style requirements, e.g. `flask==3.0.0`, or `black @ https://...`."
|
||||
description = "PEP 508 style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`."
|
||||
)
|
||||
)]
|
||||
pub override_dependencies: Option<Vec<Requirement<VerbatimParsedUrl>>>,
|
||||
|
|
@ -129,31 +129,245 @@ pub struct ResolverInstallerOptions {
|
|||
/// The index provided by this setting is given lower priority than any indexes specified via
|
||||
/// [`extra_index_url`](#extra-index-url).
|
||||
#[option(
|
||||
default = "https://pypi.org/simple",
|
||||
default = "\"https://pypi.org/simple\"",
|
||||
value_type = "str",
|
||||
example = r#"
|
||||
index-url = "https://pypi.org/simple"
|
||||
"#
|
||||
)]
|
||||
pub index_url: Option<IndexUrl>,
|
||||
/// Extra URLs of package indexes to use, in addition to `--index-url`.
|
||||
///
|
||||
/// Accepts either a repository compliant with PEP 503 (the simple repository API), or a local
|
||||
/// directory laid out in the same format.
|
||||
///
|
||||
/// All indexes provided via this flag take priority over the index specified by
|
||||
/// [`index_url`](#index-url). When multiple indexes are provided, earlier values take priority.
|
||||
///
|
||||
/// To control uv's resolution strategy when multiple indexes are present, see
|
||||
/// [`index_strategy`](#index-strategy).
|
||||
#[option(
|
||||
default = "[]",
|
||||
value_type = "list[str]",
|
||||
example = r#"
|
||||
extra-index-url = ["https://download.pytorch.org/whl/cpu"]
|
||||
"#
|
||||
)]
|
||||
pub extra_index_url: Option<Vec<IndexUrl>>,
|
||||
/// Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and
|
||||
/// those provided via `--find-links`.
|
||||
#[option(
|
||||
default = "false",
|
||||
value_type = "bool",
|
||||
example = r#"
|
||||
no-index = true
|
||||
"#
|
||||
)]
|
||||
pub no_index: Option<bool>,
|
||||
/// Locations to search for candidate distributions, in addition to those found in the registry
|
||||
/// indexes.
|
||||
///
|
||||
/// If a path, the target must be a directory that contains packages as wheel files (`.whl`) or
|
||||
/// source distributions (`.tar.gz` or `.zip`) at the top level.
|
||||
///
|
||||
/// If a URL, the page must contain a flat list of links to package files adhering to the
|
||||
/// formats described above.
|
||||
#[option(
|
||||
default = "[]",
|
||||
value_type = "list[str]",
|
||||
example = r#"
|
||||
find-links = ["https://download.pytorch.org/whl/torch_stable.html"]
|
||||
"#
|
||||
)]
|
||||
pub find_links: Option<Vec<FlatIndexLocation>>,
|
||||
/// The strategy to use when resolving against multiple index URLs.
|
||||
///
|
||||
/// By default, `uv` will stop at the first index on which a given package is available, and
|
||||
/// limit resolutions to those present on that first index (`first-match`). This prevents
|
||||
/// "dependency confusion" attacks, whereby an attack can upload a malicious package under the
|
||||
/// same name to a secondary.
|
||||
///
|
||||
/// Possible values:
|
||||
///
|
||||
/// - `"first-index"`: Only use results from the first index that returns a match for a given package name.
|
||||
/// - `"unsafe-first-match"`: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next.
|
||||
/// - `"unsafe-best-match"`: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index.
|
||||
#[option(
|
||||
default = "\"first-index\"",
|
||||
value_type = "str",
|
||||
example = r#"
|
||||
index-strategy = "unsafe-best-match"
|
||||
"#
|
||||
)]
|
||||
pub index_strategy: Option<IndexStrategy>,
|
||||
/// Attempt to use `keyring` for authentication for index URLs.
|
||||
///
|
||||
/// At present, only `--keyring-provider subprocess` is supported, which configures `uv` to
|
||||
/// use the `keyring` CLI to handle authentication.
|
||||
#[option(
|
||||
default = "\"disabled\"",
|
||||
value_type = "str",
|
||||
example = r#"
|
||||
keyring-provider = "subprocess"
|
||||
"#
|
||||
)]
|
||||
pub keyring_provider: Option<KeyringProviderType>,
|
||||
/// 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`).
|
||||
#[option(
|
||||
default = "\"highest\"",
|
||||
value_type = "str",
|
||||
example = r#"
|
||||
resolution = "lowest-direct"
|
||||
"#
|
||||
)]
|
||||
pub resolution: Option<ResolutionMode>,
|
||||
/// The strategy to use when considering pre-release versions.
|
||||
///
|
||||
/// By default, `uv` will accept pre-releases for packages that _only_ publish pre-releases,
|
||||
/// along with first-party requirements that contain an explicit pre-release marker in the
|
||||
/// declared specifiers (`if-necessary-or-explicit`).
|
||||
#[option(
|
||||
default = "\"if-necessary-or-explicit\"",
|
||||
value_type = "str",
|
||||
example = r#"
|
||||
prerelease = "allow"
|
||||
"#
|
||||
)]
|
||||
pub prerelease: Option<PreReleaseMode>,
|
||||
/// Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs.
|
||||
#[option(
|
||||
default = "{}",
|
||||
value_type = "dict",
|
||||
example = r#"
|
||||
config-settings = { "editable_mode": "compat" }
|
||||
"#
|
||||
)]
|
||||
pub config_settings: Option<ConfigSettings>,
|
||||
/// 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 UTC dates in the same
|
||||
/// format (e.g., `2006-12-02`).
|
||||
#[option(
|
||||
default = "None",
|
||||
value_type = "str",
|
||||
example = r#"
|
||||
exclude-newer = "2006-12-02"
|
||||
"#
|
||||
)]
|
||||
pub exclude_newer: Option<ExcludeNewer>,
|
||||
/// 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.
|
||||
#[option(
|
||||
default = "\"clone\" (macOS) or \"hardlink\" (Linux, Windows)",
|
||||
value_type = "str",
|
||||
example = r#"
|
||||
link-mode = "copy"
|
||||
"#
|
||||
)]
|
||||
pub link_mode: Option<LinkMode>,
|
||||
/// Compile Python files to bytecode after installation.
|
||||
///
|
||||
/// By default, does not compile Python (`.py`) files to bytecode (`__pycache__/*.pyc`), instead
|
||||
/// Python lazily does the compilation the first time a module is imported. In cases where the
|
||||
/// first start time matters, such as CLI applications and docker containers, this option can
|
||||
/// trade longer install time for faster startup.
|
||||
///
|
||||
/// The compile option will process the entire site-packages directory for consistency and
|
||||
/// (like pip) ignore all errors.
|
||||
#[option(
|
||||
default = "false",
|
||||
value_type = "bool",
|
||||
example = r#"
|
||||
compile-bytecode = true
|
||||
"#
|
||||
)]
|
||||
pub compile_bytecode: Option<bool>,
|
||||
/// Allow package upgrades, ignoring pinned versions in any existing output file.
|
||||
#[option(
|
||||
default = "false",
|
||||
value_type = "bool",
|
||||
example = r#"
|
||||
upgrade = true
|
||||
"#
|
||||
)]
|
||||
pub upgrade: Option<bool>,
|
||||
/// Allow upgrades for a specific package, ignoring pinned versions in any existing output
|
||||
/// file.
|
||||
///
|
||||
/// Accepts both standalone package names (`ruff`) and version specifiers (`ruff<0.5.0`).
|
||||
#[option(
|
||||
default = "[]",
|
||||
value_type = "list[str]",
|
||||
example = r#"
|
||||
upgrade-package = ["ruff"]
|
||||
"#
|
||||
)]
|
||||
pub upgrade_package: Option<Vec<Requirement<VerbatimParsedUrl>>>,
|
||||
/// Reinstall all packages, regardless of whether they're already installed.
|
||||
#[option(
|
||||
default = "false",
|
||||
value_type = "bool",
|
||||
example = r#"
|
||||
reinstall = true
|
||||
"#
|
||||
)]
|
||||
pub reinstall: Option<bool>,
|
||||
/// Reinstall a specific package, regardless of whether it's already installed.
|
||||
#[option(
|
||||
default = "[]",
|
||||
value_type = "list[str]",
|
||||
example = r#"
|
||||
reinstall-package = ["ruff"]
|
||||
"#
|
||||
)]
|
||||
pub reinstall_package: Option<Vec<PackageName>>,
|
||||
/// Don't build source distributions.
|
||||
///
|
||||
/// When enabled, resolving will not run arbitrary Python code. The cached wheels of
|
||||
/// already-built source distributions will be reused, but operations that require building
|
||||
/// distributions will exit with an error.
|
||||
#[option(
|
||||
default = "false",
|
||||
value_type = "bool",
|
||||
example = r#"
|
||||
no-build = true
|
||||
"#
|
||||
)]
|
||||
pub no_build: Option<bool>,
|
||||
/// Don't build source distributions for a specific package.
|
||||
#[option(
|
||||
default = "[]",
|
||||
value_type = "list[str]",
|
||||
example = r#"
|
||||
no-build-package = ["ruff"]
|
||||
"#
|
||||
)]
|
||||
pub no_build_package: Option<Vec<PackageName>>,
|
||||
/// Don't install pre-built wheels.
|
||||
///
|
||||
/// The given packages will be built and installed from source. The resolver will still use
|
||||
/// pre-built wheels to extract package metadata, if available.
|
||||
#[option(
|
||||
default = "false",
|
||||
value_type = "bool",
|
||||
example = r#"
|
||||
no-binary = true
|
||||
"#
|
||||
)]
|
||||
pub no_binary: Option<bool>,
|
||||
/// Don't install pre-built wheels for a specific package.
|
||||
#[option(
|
||||
default = "[]",
|
||||
value_type = "list[str]",
|
||||
example = r#"
|
||||
no-binary-package = ["ruff"]
|
||||
"#
|
||||
)]
|
||||
pub no_binary_package: Option<Vec<PackageName>>,
|
||||
}
|
||||
|
||||
|
|
|
|||
539
docs/settings.md
539
docs/settings.md
|
|
@ -1,4 +1,192 @@
|
|||
## Global
|
||||
#### [`compile-bytecode`](#compile-bytecode) {: #compile-bytecode }
|
||||
|
||||
Compile Python files to bytecode after installation.
|
||||
|
||||
By default, does not compile Python (`.py`) files to bytecode (`__pycache__/*.pyc`), instead
|
||||
Python lazily does the compilation the first time a module is imported. In cases where the
|
||||
first start time matters, such as CLI applications and docker containers, this option can
|
||||
trade longer install time for faster startup.
|
||||
|
||||
The compile option will process the entire site-packages directory for consistency and
|
||||
(like pip) ignore all errors.
|
||||
|
||||
**Default value**: `false`
|
||||
|
||||
**Type**: `bool`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
compile-bytecode = true
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
compile-bytecode = true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`config-settings`](#config-settings) {: #config-settings }
|
||||
|
||||
Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs.
|
||||
|
||||
**Default value**: `{}`
|
||||
|
||||
**Type**: `dict`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
config-settings = { "editable_mode": "compat" }
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
config-settings = { "editable_mode": "compat" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`exclude-newer`](#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 UTC dates in the same
|
||||
format (e.g., `2006-12-02`).
|
||||
|
||||
**Default value**: `None`
|
||||
|
||||
**Type**: `str`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
exclude-newer = "2006-12-02"
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
exclude-newer = "2006-12-02"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`extra-index-url`](#extra-index-url) {: #extra-index-url }
|
||||
|
||||
Extra URLs of package indexes to use, in addition to `--index-url`.
|
||||
|
||||
Accepts either a repository compliant with PEP 503 (the simple repository API), or a local
|
||||
directory laid out in the same format.
|
||||
|
||||
All indexes provided via this flag take priority over the index specified by
|
||||
[`index_url`](#index-url). When multiple indexes are provided, earlier values take priority.
|
||||
|
||||
To control uv's resolution strategy when multiple indexes are present, see
|
||||
[`index_strategy`](#index-strategy).
|
||||
|
||||
**Default value**: `[]`
|
||||
|
||||
**Type**: `list[str]`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
extra-index-url = ["https://download.pytorch.org/whl/cpu"]
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
extra-index-url = ["https://download.pytorch.org/whl/cpu"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`find-links`](#find-links) {: #find-links }
|
||||
|
||||
Locations to search for candidate distributions, in addition to those found in the registry
|
||||
indexes.
|
||||
|
||||
If a path, the target must be a directory that contains packages as wheel files (`.whl`) or
|
||||
source distributions (`.tar.gz` or `.zip`) at the top level.
|
||||
|
||||
If a URL, the page must contain a flat list of links to package files adhering to the
|
||||
formats described above.
|
||||
|
||||
**Default value**: `[]`
|
||||
|
||||
**Type**: `list[str]`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
find-links = ["https://download.pytorch.org/whl/torch_stable.html"]
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
find-links = ["https://download.pytorch.org/whl/torch_stable.html"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`index-strategy`](#index-strategy) {: #index-strategy }
|
||||
|
||||
The strategy to use when resolving against multiple index URLs.
|
||||
|
||||
By default, `uv` will stop at the first index on which a given package is available, and
|
||||
limit resolutions to those present on that first index (`first-match`). This prevents
|
||||
"dependency confusion" attacks, whereby an attack can upload a malicious package under the
|
||||
same name to a secondary.
|
||||
|
||||
Possible values:
|
||||
|
||||
- `"first-index"`: Only use results from the first index that returns a match for a given package name.
|
||||
- `"unsafe-first-match"`: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next.
|
||||
- `"unsafe-best-match"`: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index.
|
||||
|
||||
**Default value**: `"first-index"`
|
||||
|
||||
**Type**: `str`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
index-strategy = "unsafe-best-match"
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
index-strategy = "unsafe-best-match"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`index-url`](#index-url) {: #index-url }
|
||||
|
||||
The URL of the Python package index (by default: <https://pypi.org/simple>).
|
||||
|
|
@ -9,7 +197,7 @@ directory laid out in the same format.
|
|||
The index provided by this setting is given lower priority than any indexes specified via
|
||||
[`extra_index_url`](#extra-index-url).
|
||||
|
||||
**Default value**: `https://pypi.org/simple`
|
||||
**Default value**: `"https://pypi.org/simple"`
|
||||
|
||||
**Type**: `str`
|
||||
|
||||
|
|
@ -30,6 +218,62 @@ The index provided by this setting is given lower priority than any indexes spec
|
|||
|
||||
---
|
||||
|
||||
#### [`keyring-provider`](#keyring-provider) {: #keyring-provider }
|
||||
|
||||
Attempt to use `keyring` for authentication for index URLs.
|
||||
|
||||
At present, only `--keyring-provider subprocess` is supported, which configures `uv` to
|
||||
use the `keyring` CLI to handle authentication.
|
||||
|
||||
**Default value**: `"disabled"`
|
||||
|
||||
**Type**: `str`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
keyring-provider = "subprocess"
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
keyring-provider = "subprocess"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`link-mode`](#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.
|
||||
|
||||
**Default value**: `"clone" (macOS) or "hardlink" (Linux, Windows)`
|
||||
|
||||
**Type**: `str`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
link-mode = "copy"
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
link-mode = "copy"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`managed`](#managed) {: #managed }
|
||||
|
||||
Whether the project is managed by `uv`. If `false`, `uv` will ignore the project when
|
||||
|
|
@ -56,6 +300,299 @@ Whether the project is managed by `uv`. If `false`, `uv` will ignore the project
|
|||
|
||||
---
|
||||
|
||||
#### [`no-binary`](#no-binary) {: #no-binary }
|
||||
|
||||
Don't install pre-built wheels.
|
||||
|
||||
The given packages will be built and installed from source. The resolver will still use
|
||||
pre-built wheels to extract package metadata, if available.
|
||||
|
||||
**Default value**: `false`
|
||||
|
||||
**Type**: `bool`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
no-binary = true
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
no-binary = true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`no-binary-package`](#no-binary-package) {: #no-binary-package }
|
||||
|
||||
Don't install pre-built wheels for a specific package.
|
||||
|
||||
**Default value**: `[]`
|
||||
|
||||
**Type**: `list[str]`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
no-binary-package = ["ruff"]
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
no-binary-package = ["ruff"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`no-build`](#no-build) {: #no-build }
|
||||
|
||||
Don't build source distributions.
|
||||
|
||||
When enabled, resolving will not run arbitrary Python code. The cached wheels of
|
||||
already-built source distributions will be reused, but operations that require building
|
||||
distributions will exit with an error.
|
||||
|
||||
**Default value**: `false`
|
||||
|
||||
**Type**: `bool`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
no-build = true
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
no-build = true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`no-build-package`](#no-build-package) {: #no-build-package }
|
||||
|
||||
Don't build source distributions for a specific package.
|
||||
|
||||
**Default value**: `[]`
|
||||
|
||||
**Type**: `list[str]`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
no-build-package = ["ruff"]
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
no-build-package = ["ruff"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`no-index`](#no-index) {: #no-index }
|
||||
|
||||
Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and
|
||||
those provided via `--find-links`.
|
||||
|
||||
**Default value**: `false`
|
||||
|
||||
**Type**: `bool`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
no-index = true
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
no-index = 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,
|
||||
along with first-party requirements that contain an explicit pre-release marker in the
|
||||
declared specifiers (`if-necessary-or-explicit`).
|
||||
|
||||
**Default value**: `"if-necessary-or-explicit"`
|
||||
|
||||
**Type**: `str`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
prerelease = "allow"
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
prerelease = "allow"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`reinstall`](#reinstall) {: #reinstall }
|
||||
|
||||
Reinstall all packages, regardless of whether they're already installed.
|
||||
|
||||
**Default value**: `false`
|
||||
|
||||
**Type**: `bool`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
reinstall = true
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
reinstall = true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`reinstall-package`](#reinstall-package) {: #reinstall-package }
|
||||
|
||||
Reinstall a specific package, regardless of whether it's already installed.
|
||||
|
||||
**Default value**: `[]`
|
||||
|
||||
**Type**: `list[str]`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
reinstall-package = ["ruff"]
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
reinstall-package = ["ruff"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`resolution`](#resolution) {: #resolution }
|
||||
|
||||
The strategy to use when selecting between the different compatible versions for a given
|
||||
package requirement.
|
||||
|
||||
By default, `uv` will use the latest compatible version of each package (`highest`).
|
||||
|
||||
**Default value**: `"highest"`
|
||||
|
||||
**Type**: `str`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
resolution = "lowest-direct"
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
resolution = "lowest-direct"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`upgrade`](#upgrade) {: #upgrade }
|
||||
|
||||
Allow package upgrades, ignoring pinned versions in any existing output file.
|
||||
|
||||
**Default value**: `false`
|
||||
|
||||
**Type**: `bool`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
upgrade = true
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
upgrade = true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### [`upgrade-package`](#upgrade-package) {: #upgrade-package }
|
||||
|
||||
Allow upgrades for a specific package, ignoring pinned versions in any existing output
|
||||
file.
|
||||
|
||||
Accepts both standalone package names (`ruff`) and version specifiers (`ruff<0.5.0`).
|
||||
|
||||
**Default value**: `[]`
|
||||
|
||||
**Type**: `list[str]`
|
||||
|
||||
**Example usage**:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
upgrade-package = ["ruff"]
|
||||
```
|
||||
=== "uv.toml"
|
||||
|
||||
```toml
|
||||
|
||||
upgrade-package = ["ruff"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `pip`
|
||||
|
||||
Settings that are specific to the `uv pip` command-line interface.
|
||||
|
|
|
|||
23
uv.schema.json
generated
23
uv.schema.json
generated
|
|
@ -11,12 +11,14 @@
|
|||
]
|
||||
},
|
||||
"compile-bytecode": {
|
||||
"description": "Compile Python files to bytecode after installation.\n\nBy default, does not compile Python (`.py`) files to bytecode (`__pycache__/*.pyc`), instead Python lazily does the compilation the first time a module is imported. In cases where the first start time matters, such as CLI applications and docker containers, this option can trade longer install time for faster startup.\n\nThe compile option will process the entire site-packages directory for consistency and (like pip) ignore all errors.",
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"config-settings": {
|
||||
"description": "Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs.",
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/definitions/ConfigSettings"
|
||||
|
|
@ -27,7 +29,7 @@
|
|||
]
|
||||
},
|
||||
"dev-dependencies": {
|
||||
"description": "PEP 508-style requirements, e.g., `flask==3.0.0`, or `black @ https://...`.",
|
||||
"description": "PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`.",
|
||||
"type": [
|
||||
"array",
|
||||
"null"
|
||||
|
|
@ -37,6 +39,7 @@
|
|||
}
|
||||
},
|
||||
"exclude-newer": {
|
||||
"description": "Limit candidate packages to those that were uploaded prior to the given date.\n\nAccepts both RFC 3339 timestamps (e.g., `2006-12-02T02:07:43Z`) and UTC dates in the same format (e.g., `2006-12-02`).",
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/definitions/ExcludeNewer"
|
||||
|
|
@ -47,6 +50,7 @@
|
|||
]
|
||||
},
|
||||
"extra-index-url": {
|
||||
"description": "Extra URLs of package indexes to use, in addition to `--index-url`.\n\nAccepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.\n\nAll indexes provided via this flag take priority over the index specified by [`index_url`](#index-url). When multiple indexes are provided, earlier values take priority.\n\nTo control uv's resolution strategy when multiple indexes are present, see [`index_strategy`](#index-strategy).",
|
||||
"type": [
|
||||
"array",
|
||||
"null"
|
||||
|
|
@ -56,6 +60,7 @@
|
|||
}
|
||||
},
|
||||
"find-links": {
|
||||
"description": "Locations to search for candidate distributions, in addition to those found in the registry indexes.\n\nIf a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (`.tar.gz` or `.zip`) at the top level.\n\nIf a URL, the page must contain a flat list of links to package files adhering to the formats described above.",
|
||||
"type": [
|
||||
"array",
|
||||
"null"
|
||||
|
|
@ -65,6 +70,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.",
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/definitions/IndexStrategy"
|
||||
|
|
@ -86,6 +92,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.",
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/definitions/KeyringProviderType"
|
||||
|
|
@ -96,6 +103,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 Windows.",
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/definitions/LinkMode"
|
||||
|
|
@ -119,12 +127,14 @@
|
|||
]
|
||||
},
|
||||
"no-binary": {
|
||||
"description": "Don't install pre-built wheels.\n\nThe given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.",
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"no-binary-package": {
|
||||
"description": "Don't install pre-built wheels for a specific package.",
|
||||
"type": [
|
||||
"array",
|
||||
"null"
|
||||
|
|
@ -134,12 +144,14 @@
|
|||
}
|
||||
},
|
||||
"no-build": {
|
||||
"description": "Don't build source distributions.\n\nWhen enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an error.",
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"no-build-package": {
|
||||
"description": "Don't build source distributions for a specific package.",
|
||||
"type": [
|
||||
"array",
|
||||
"null"
|
||||
|
|
@ -155,6 +167,7 @@
|
|||
]
|
||||
},
|
||||
"no-index": {
|
||||
"description": "Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and those provided via `--find-links`.",
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
|
|
@ -167,7 +180,7 @@
|
|||
]
|
||||
},
|
||||
"override-dependencies": {
|
||||
"description": "PEP 508 style requirements, e.g. `flask==3.0.0`, or `black @ https://...`.",
|
||||
"description": "PEP 508 style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`.",
|
||||
"type": [
|
||||
"array",
|
||||
"null"
|
||||
|
|
@ -187,6 +200,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`).",
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/definitions/PreReleaseMode"
|
||||
|
|
@ -223,12 +237,14 @@
|
|||
]
|
||||
},
|
||||
"reinstall": {
|
||||
"description": "Reinstall all packages, regardless of whether they're already installed.",
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"reinstall-package": {
|
||||
"description": "Reinstall a specific package, regardless of whether it's already installed.",
|
||||
"type": [
|
||||
"array",
|
||||
"null"
|
||||
|
|
@ -238,6 +254,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`).",
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/definitions/ResolutionMode"
|
||||
|
|
@ -257,12 +274,14 @@
|
|||
}
|
||||
},
|
||||
"upgrade": {
|
||||
"description": "Allow package upgrades, ignoring pinned versions in any existing output file.",
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"upgrade-package": {
|
||||
"description": "Allow upgrades for a specific package, ignoring pinned versions in any existing output file.\n\nAccepts both standalone package names (`ruff`) and version specifiers (`ruff<0.5.0`).",
|
||||
"type": [
|
||||
"array",
|
||||
"null"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue