From 6b44e691b7b7753309fb886d9aefba0f9248648c Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Mon, 30 Sep 2024 20:47:37 -0400 Subject: [PATCH] Review feedback --- crates/uv-cli/src/lib.rs | 8 +- crates/uv-distribution-types/src/index.rs | 2 +- crates/uv-distribution-types/src/index_url.rs | 8 +- crates/uv-pypi-types/src/requirement.rs | 2 +- crates/uv-settings/src/settings.rs | 37 +---- crates/uv-workspace/src/pyproject.rs | 9 +- crates/uv/tests/lock.rs | 156 +++++++++++++++++- crates/uv/tests/show_settings.rs | 2 +- crates/uv/tests/sync.rs | 1 + docs/concepts/dependencies.md | 2 +- docs/configuration/environment.md | 8 +- docs/configuration/indexes.md | 10 +- docs/reference/cli.md | 120 ++++---------- docs/reference/settings.md | 20 ++- uv.schema.json | 4 +- 15 files changed, 228 insertions(+), 161 deletions(-) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 1be62822baf45..4984e5cc489e5 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -3746,19 +3746,17 @@ pub struct IndexArgs { #[arg(long, env = "UV_DEFAULT_INDEX", value_parser = parse_default_index_source, help_heading = "Index options")] pub default_index: Option>, - /// The URL of the Python package index (by default: ). + /// (Deprecated: use `--default-index` instead) The URL of the Python package index (by default: ). /// /// Accepts either a repository compliant with PEP 503 (the simple repository API), or a local /// directory laid out in the same format. /// /// The index given by this flag is given lower priority than all other /// indexes specified via the `--extra-index-url` flag. - /// - /// (Deprecated: use `--default-index` instead.) #[arg(long, short, env = "UV_INDEX_URL", value_parser = parse_index_url, help_heading = "Index options")] pub index_url: Option>, - /// Extra URLs of package indexes to use, in addition to `--index-url`. + /// (Deprecated: use `--index` instead) Extra URLs of package indexes to use, in addition to `--index-url`. /// /// Accepts either a repository compliant with PEP 503 (the simple repository API), or a local /// directory laid out in the same format. @@ -3766,8 +3764,6 @@ pub struct IndexArgs { /// 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. - /// - /// (Deprecated: use `--index` instead.) #[arg(long, env = "UV_EXTRA_INDEX_URL", value_delimiter = ' ', value_parser = parse_index_url, help_heading = "Index options")] pub extra_index_url: Option>>, diff --git a/crates/uv-distribution-types/src/index.rs b/crates/uv-distribution-types/src/index.rs index 4d335a8f7302d..baa7d81757306 100644 --- a/crates/uv-distribution-types/src/index.rs +++ b/crates/uv-distribution-types/src/index.rs @@ -26,7 +26,7 @@ pub struct Index { pub url: IndexUrl, /// Mark the index as explicit. /// - /// Explicit indexes will _only_ be used when explicitly enabled via a `[tool.uv.sources]` + /// Explicit indexes will _only_ be used when explicitly requested via a `[tool.uv.sources]` /// definition, as in: /// /// ```toml diff --git a/crates/uv-distribution-types/src/index_url.rs b/crates/uv-distribution-types/src/index_url.rs index 6f7b8ad42a226..f868f8c835286 100644 --- a/crates/uv-distribution-types/src/index_url.rs +++ b/crates/uv-distribution-types/src/index_url.rs @@ -298,8 +298,8 @@ impl From for FlatIndexLocation { /// The index locations to use for fetching packages. By default, uses the PyPI index. /// -/// From a pip perspective, this type merges `--index-url`, `--extra-index-url`, and `--find-links`, -/// along with the uv-specific `--index` and `--default-index` options. +/// This type merges the legacy `--index-url`, `--extra-index-url`, and `--find-links` options, +/// along with the uv-specific `--index` and `--default-index`. #[derive(Default, Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] #[serde(rename_all = "kebab-case", deny_unknown_fields)] pub struct IndexLocations { @@ -451,8 +451,8 @@ impl<'a> IndexLocations { /// The index URLs to use for fetching packages. /// -/// From a pip perspective, this type merges `--index-url` and `--extra-index-url`, along with the -/// uv-specific `--index` and `--default-index` options. +/// This type merges the legacy `--index-url` and `--extra-index-url` options, along with the +/// uv-specific `--index` and `--default-index`. #[derive(Default, Debug, Clone, PartialEq, Eq)] pub struct IndexUrls { indexes: Vec, diff --git a/crates/uv-pypi-types/src/requirement.rs b/crates/uv-pypi-types/src/requirement.rs index ea1ec96cb57c8..65af544cc7ce6 100644 --- a/crates/uv-pypi-types/src/requirement.rs +++ b/crates/uv-pypi-types/src/requirement.rs @@ -318,7 +318,7 @@ pub enum RequirementSource { /// The requirement has a version specifier, such as `foo >1,<2`. Registry { specifier: VersionSpecifiers, - /// Choose a version from the index with this name. + /// Choose a version from the index at the given URL. index: Option, }, // TODO(konsti): Track and verify version specifier from `project.dependencies` matches the diff --git a/crates/uv-settings/src/settings.rs b/crates/uv-settings/src/settings.rs index a31252d9a2791..c8b8a6c26726f 100644 --- a/crates/uv-settings/src/settings.rs +++ b/crates/uv-settings/src/settings.rs @@ -302,7 +302,10 @@ pub struct ResolverInstallerOptions { /// (the simple repository API), or a local directory laid out in the same format. /// /// Indexes are considered in the order in which they're defined, such that the first-defined - /// index has the highest priority. + /// index has the highest priority. Further, the indexes provided by this setting are given + /// higher priority than any indexes specified via [`index_url`](#index-url) or + /// [`extra_index_url`](#extra-index-url). uv will only consider the first index that contains + /// a given package, unless an alternative [index strategy](#index-strategy) is specified. /// /// If an index is marked as `explicit = true`, it will be used exclusively for those /// dependencies that select it explicitly via `[tool.uv.sources]`, as in: @@ -317,9 +320,9 @@ pub struct ResolverInstallerOptions { /// torch = { index = "pytorch" } /// ``` /// - /// Marking an index as `default = true` will disable the PyPI default index and move the - /// index to the end of the prioritized list, such that it is used when a package is not found - /// on any other index. + /// If an index is marked as `default = true`, it will be moved to the end of the prioritized list, such that it is + /// given the lowest priority when resolving packages. Additionally, marking an index as default will disable the + /// PyPI default index. #[option( default = "\"[]\"", value_type = "dict", @@ -745,32 +748,6 @@ pub struct PipOptions { "# )] pub prefix: Option, - /// The indexes to use when resolving dependencies. - /// - /// Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/) - /// (the simple repository API), or a local directory laid out in the same format. - /// - /// Indexes are considered in the order in which they're defined, such that the first-defined - /// index has the highest priority. Further, the indexes provided by this setting are given - /// higher priority than any indexes specified via [`index_url`](#index-url) or - /// [`extra_index_url`](#extra-index-url). - /// - /// If an index is marked as `explicit = true`, it will be used exclusively for those - /// dependencies that select it explicitly via `[tool.uv.sources]`, as in: - /// - /// ```toml - /// [[tool.uv.index]] - /// name = "pytorch" - /// url = "https://download.pytorch.org/whl/cu121" - /// explicit = true - /// - /// [tool.uv.sources] - /// torch = { index = "pytorch" } - /// ``` - /// - /// If an index is marked as `default = true`, it will be moved to the front of the list of - /// the list of indexes, such that it is given the highest priority when resolving packages. - /// Additionally, marking an index as default will disable the PyPI default index. #[serde(skip)] #[cfg_attr(feature = "schemars", schemars(skip))] pub index: Option>, diff --git a/crates/uv-workspace/src/pyproject.rs b/crates/uv-workspace/src/pyproject.rs index d397cd6aec982..95bbe4ac1c27e 100644 --- a/crates/uv-workspace/src/pyproject.rs +++ b/crates/uv-workspace/src/pyproject.rs @@ -163,7 +163,8 @@ pub struct ToolUv { /// Indexes are considered in the order in which they're defined, such that the first-defined /// index has the highest priority. Further, the indexes provided by this setting are given /// higher priority than any indexes specified via [`index_url`](#index-url) or - /// [`extra_index_url`](#extra-index-url). + /// [`extra_index_url`](#extra-index-url). uv will only consider the first index that contains + /// a given package, unless an alternative [index strategy](#index-strategy) is specified. /// /// If an index is marked as `explicit = true`, it will be used exclusively for those /// dependencies that select it explicitly via `[tool.uv.sources]`, as in: @@ -178,9 +179,9 @@ pub struct ToolUv { /// torch = { index = "pytorch" } /// ``` /// - /// If an index is marked as `default = true`, it will be moved to the front of the list of - /// the list of indexes, such that it is given the highest priority when resolving packages. - /// Additionally, marking an index as default will disable the PyPI default index. + /// If an index is marked as `default = true`, it will be moved to the end of the prioritized list, such that it is + /// given the lowest priority when resolving packages. Additionally, marking an index as default will disable the + /// PyPI default index. #[option( default = "\"[]\"", value_type = "dict", diff --git a/crates/uv/tests/lock.rs b/crates/uv/tests/lock.rs index b772b3c11bcb7..e94492f24f1fb 100644 --- a/crates/uv/tests/lock.rs +++ b/crates/uv/tests/lock.rs @@ -12078,7 +12078,7 @@ fn lock_default_index() -> Result<()> { } #[test] -fn lock_explicit_index_cli() -> Result<()> { +fn lock_named_index_cli() -> Result<()> { let context = TestContext::new("3.12"); let pyproject_toml = context.temp_dir.child("pyproject.toml"); @@ -12125,8 +12125,8 @@ fn lock_explicit_index_cli() -> Result<()> { /// If a name is reused, the higher-priority index should "overwrite" the lower-priority index. /// In other words, the lower-priority index should be ignored entirely during implicit resolution. /// -/// In this test, we should use PyPI (the default index) rather than falling back to Test PyPI, -/// which should be ignored. +/// In this test, we should use PyPI (the default index) and ignore `https://example.com` entirely. +/// (Querying `https://example.com` would fail with a 500.) #[test] fn lock_repeat_named_index() -> Result<()> { let context = TestContext::new("3.12"); @@ -12146,10 +12146,11 @@ fn lock_repeat_named_index() -> Result<()> { [[tool.uv.index]] name = "pytorch" - url = "https://test.pypi.org/simple" + url = "https://example.com" "#, )?; + // Fall back to PyPI, since `iniconfig` doesn't exist on the PyTorch index. uv_snapshot!(context.filters(), context.lock(), @r###" success: true exit_code: 0 @@ -12198,6 +12199,153 @@ fn lock_repeat_named_index() -> Result<()> { Ok(()) } +/// If a name is reused, the higher-priority index should "overwrite" the lower-priority index. +/// This includes names passed in via the CLI. +#[test] +fn lock_repeat_named_index_cli() -> Result<()> { + let context = TestContext::new("3.12"); + + let pyproject_toml = context.temp_dir.child("pyproject.toml"); + pyproject_toml.write_str( + r#" + [project] + name = "project" + version = "0.1.0" + requires-python = ">=3.12" + dependencies = ["jinja2==3.1.2"] + + [[tool.uv.index]] + name = "pytorch" + url = "https://download.pytorch.org/whl/cu121" + "#, + )?; + + // Resolve to the PyTorch index. + uv_snapshot!(context.filters(), context.lock().env_remove("UV_EXCLUDE_NEWER"), @r###" + success: true + exit_code: 0 + ----- stdout ----- + + ----- stderr ----- + Resolved 3 packages in [TIME] + "###); + + let lock = fs_err::read_to_string(context.temp_dir.join("uv.lock")).unwrap(); + + insta::with_settings!({ + filters => context.filters(), + }, { + assert_snapshot!( + lock, @r###" + version = 1 + requires-python = ">=3.12" + + [[package]] + name = "jinja2" + version = "3.1.2" + source = { registry = "https://download.pytorch.org/whl/cu121" } + dependencies = [ + { name = "markupsafe" }, + ] + wheels = [ + { url = "https://download.pytorch.org/whl/Jinja2-3.1.2-py3-none-any.whl", hash = "sha256:6088930bfe239f0e6710546ab9c19c9ef35e29792895fed6e6e31a023a182a61" }, + ] + + [[package]] + name = "markupsafe" + version = "2.1.5" + source = { registry = "https://download.pytorch.org/whl/cu121" } + wheels = [ + { url = "https://download.pytorch.org/whl/MarkupSafe-2.1.5-cp312-cp312-macosx_10_9_universal2.whl", hash = "sha256:8dec4936e9c3100156f8a2dc89c4b88d5c435175ff03413b443469c7c8c5f4d1" }, + { url = "https://download.pytorch.org/whl/MarkupSafe-2.1.5-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:3c6b973f22eb18a789b1460b4b91bf04ae3f0c4234a0a6aa6b0a92f6f7b951d4" }, + { url = "https://download.pytorch.org/whl/MarkupSafe-2.1.5-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ac07bad82163452a6884fe8fa0963fb98c2346ba78d779ec06bd7a6262132aee" }, + { url = "https://download.pytorch.org/whl/MarkupSafe-2.1.5-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f5dfb42c4604dddc8e4305050aa6deb084540643ed5804d7455b5df8fe16f5e5" }, + { url = "https://download.pytorch.org/whl/MarkupSafe-2.1.5-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:ea3d8a3d18833cf4304cd2fc9cbb1efe188ca9b5efef2bdac7adc20594a0e46b" }, + { url = "https://download.pytorch.org/whl/MarkupSafe-2.1.5-cp312-cp312-win_amd64.whl", hash = "sha256:823b65d8706e32ad2df51ed89496147a42a2a6e01c13cfb6ffb8b1e92bc910bb" }, + ] + + [[package]] + name = "project" + version = "0.1.0" + source = { virtual = "." } + dependencies = [ + { name = "jinja2" }, + ] + + [package.metadata] + requires-dist = [{ name = "jinja2", specifier = "==3.1.2" }] + "### + ); + }); + + // Resolve to PyPI, since the PyTorch index is replaced by the Packse index, which doesn't + // include `jinja2`. + uv_snapshot!(context.filters(), context.lock().arg("--index").arg(format!("pytorch={}", packse_index_url())).env_remove("UV_EXCLUDE_NEWER"), @r###" + success: true + exit_code: 0 + ----- stdout ----- + + ----- stderr ----- + Resolved 3 packages in [TIME] + "###); + + let lock = fs_err::read_to_string(context.temp_dir.join("uv.lock")).unwrap(); + + insta::with_settings!({ + filters => context.filters(), + }, { + assert_snapshot!( + lock, @r###" + version = 1 + requires-python = ">=3.12" + + [[package]] + name = "jinja2" + version = "3.1.2" + source = { registry = "https://pypi.org/simple" } + dependencies = [ + { name = "markupsafe" }, + ] + sdist = { url = "https://files.pythonhosted.org/packages/7a/ff/75c28576a1d900e87eb6335b063fab47a8ef3c8b4d88524c4bf78f670cce/Jinja2-3.1.2.tar.gz", hash = "sha256:31351a702a408a9e7595a8fc6150fc3f43bb6bf7e319770cbc0db9df9437e852", size = 268239 } + wheels = [ + { url = "https://files.pythonhosted.org/packages/bc/c3/f068337a370801f372f2f8f6bad74a5c140f6fda3d9de154052708dd3c65/Jinja2-3.1.2-py3-none-any.whl", hash = "sha256:6088930bfe239f0e6710546ab9c19c9ef35e29792895fed6e6e31a023a182a61", size = 133101 }, + ] + + [[package]] + name = "markupsafe" + version = "2.1.5" + source = { registry = "https://pypi.org/simple" } + sdist = { url = "https://files.pythonhosted.org/packages/87/5b/aae44c6655f3801e81aa3eef09dbbf012431987ba564d7231722f68df02d/MarkupSafe-2.1.5.tar.gz", hash = "sha256:d283d37a890ba4c1ae73ffadf8046435c76e7bc2247bbb63c00bd1a709c6544b", size = 19384 } + wheels = [ + { url = "https://files.pythonhosted.org/packages/53/bd/583bf3e4c8d6a321938c13f49d44024dbe5ed63e0a7ba127e454a66da974/MarkupSafe-2.1.5-cp312-cp312-macosx_10_9_universal2.whl", hash = "sha256:8dec4936e9c3100156f8a2dc89c4b88d5c435175ff03413b443469c7c8c5f4d1", size = 18215 }, + { url = "https://files.pythonhosted.org/packages/48/d6/e7cd795fc710292c3af3a06d80868ce4b02bfbbf370b7cee11d282815a2a/MarkupSafe-2.1.5-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:3c6b973f22eb18a789b1460b4b91bf04ae3f0c4234a0a6aa6b0a92f6f7b951d4", size = 14069 }, + { url = "https://files.pythonhosted.org/packages/51/b5/5d8ec796e2a08fc814a2c7d2584b55f889a55cf17dd1a90f2beb70744e5c/MarkupSafe-2.1.5-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ac07bad82163452a6884fe8fa0963fb98c2346ba78d779ec06bd7a6262132aee", size = 29452 }, + { url = "https://files.pythonhosted.org/packages/0a/0d/2454f072fae3b5a137c119abf15465d1771319dfe9e4acbb31722a0fff91/MarkupSafe-2.1.5-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f5dfb42c4604dddc8e4305050aa6deb084540643ed5804d7455b5df8fe16f5e5", size = 28462 }, + { url = "https://files.pythonhosted.org/packages/2d/75/fd6cb2e68780f72d47e6671840ca517bda5ef663d30ada7616b0462ad1e3/MarkupSafe-2.1.5-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:ea3d8a3d18833cf4304cd2fc9cbb1efe188ca9b5efef2bdac7adc20594a0e46b", size = 27869 }, + { url = "https://files.pythonhosted.org/packages/b0/81/147c477391c2750e8fc7705829f7351cf1cd3be64406edcf900dc633feb2/MarkupSafe-2.1.5-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:d050b3361367a06d752db6ead6e7edeb0009be66bc3bae0ee9d97fb326badc2a", size = 33906 }, + { url = "https://files.pythonhosted.org/packages/8b/ff/9a52b71839d7a256b563e85d11050e307121000dcebc97df120176b3ad93/MarkupSafe-2.1.5-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:bec0a414d016ac1a18862a519e54b2fd0fc8bbfd6890376898a6c0891dd82e9f", size = 32296 }, + { url = "https://files.pythonhosted.org/packages/88/07/2dc76aa51b481eb96a4c3198894f38b480490e834479611a4053fbf08623/MarkupSafe-2.1.5-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:58c98fee265677f63a4385256a6d7683ab1832f3ddd1e66fe948d5880c21a169", size = 33038 }, + { url = "https://files.pythonhosted.org/packages/96/0c/620c1fb3661858c0e37eb3cbffd8c6f732a67cd97296f725789679801b31/MarkupSafe-2.1.5-cp312-cp312-win32.whl", hash = "sha256:8590b4ae07a35970728874632fed7bd57b26b0102df2d2b233b6d9d82f6c62ad", size = 16572 }, + { url = "https://files.pythonhosted.org/packages/3f/14/c3554d512d5f9100a95e737502f4a2323a1959f6d0d01e0d0997b35f7b10/MarkupSafe-2.1.5-cp312-cp312-win_amd64.whl", hash = "sha256:823b65d8706e32ad2df51ed89496147a42a2a6e01c13cfb6ffb8b1e92bc910bb", size = 17127 }, + ] + + [[package]] + name = "project" + version = "0.1.0" + source = { virtual = "." } + dependencies = [ + { name = "jinja2" }, + ] + + [package.metadata] + requires-dist = [{ name = "jinja2", specifier = "==3.1.2" }] + "### + ); + }); + + Ok(()) +} + /// Lock a project with `package = false`, making it a virtual project. #[test] fn lock_explicit_virtual_project() -> Result<()> { diff --git a/crates/uv/tests/show_settings.rs b/crates/uv/tests/show_settings.rs index 0bded9244d379..83b3a6fb6532e 100644 --- a/crates/uv/tests/show_settings.rs +++ b/crates/uv/tests/show_settings.rs @@ -3679,7 +3679,7 @@ fn allow_insecure_host() -> anyhow::Result<()> { Ok(()) } -/// Deserialize an insecure host. +/// Prioritize indexes defined across multiple configuration sources. #[test] #[cfg_attr( windows, diff --git a/crates/uv/tests/sync.rs b/crates/uv/tests/sync.rs index 8ad052c6fba1f..e1eb31c94669e 100644 --- a/crates/uv/tests/sync.rs +++ b/crates/uv/tests/sync.rs @@ -2853,6 +2853,7 @@ fn sync_explicit() -> Result<()> { Using CPython 3.12.[X] interpreter at: [PYTHON-3.12] Creating virtual environment at: .venv Resolved 2 packages in [TIME] + Prepared 1 package in [TIME] Installed 1 package in [TIME] + idna==2.7 "###); diff --git a/docs/concepts/dependencies.md b/docs/concepts/dependencies.md index 2c96685ebe5da..084497921962d 100644 --- a/docs/concepts/dependencies.md +++ b/docs/concepts/dependencies.md @@ -70,7 +70,7 @@ stands-compliant `project.dependencies` table. During development, a project may rely on a package that isn't available on PyPI. The following additional sources are supported by uv: -- Index: A package from an explicit package index. +- Index: A package resolved from a specific package index. - Git: A Git repository. - URL: A remote wheel or source distribution. - Path: A local wheel, source distribution, or project directory. diff --git a/docs/configuration/environment.md b/docs/configuration/environment.md index 0e16a13276fb0..b45ac335fdea6 100644 --- a/docs/configuration/environment.md +++ b/docs/configuration/environment.md @@ -2,12 +2,12 @@ uv accepts the following command-line arguments as environment variables: -- `UV_INDEX`: Equivalent to the `--index` command-line argument. If set, uv will use this URL as the - base index for searching for packages. +- `UV_INDEX`: Equivalent to the `--index` command-line argument. If set, uv will use this + space-separated list of URLs as additional indexes when searching for packages. - `UV_DEFAULT_INDEX`: Equivalent to the `--default-index` command-line argument. If set, uv will use - this space-separated list of URLs as additional indexes when searching for packages. + this URL as the default index when searching for packages. - `UV_INDEX_URL`: Equivalent to the `--index-url` command-line argument. If set, uv will use this - URL as the base index for searching for packages. (Deprecated: use `UV_INDEX` instead.) + URL as the default index when searching for packages. (Deprecated: use `UV_INDEX` instead.) - `UV_EXTRA_INDEX_URL`: Equivalent to the `--extra-index-url` command-line argument. If set, uv will use this space-separated list of URLs as additional indexes when searching for packages. (Deprecated: use `UV_DEFAULT_INDEX` instead.) diff --git a/docs/configuration/indexes.md b/docs/configuration/indexes.md index 70ef968f5f9af..889b5726e6321 100644 --- a/docs/configuration/indexes.md +++ b/docs/configuration/indexes.md @@ -2,7 +2,7 @@ By default, uv uses the [Python Package Index (PyPI)](https://pypi.org) for dependency resolution and package installation. However, uv can be configured to use other package indexes, including -private indexes, via the `[[tool.uv.index]]` configuration option (and `--index`, its analogous +private indexes, via the `[[tool.uv.index]]` configuration option (and `--index`, the analogous command-line option). ## Defining an index @@ -12,9 +12,9 @@ To include an additional index when resolving dependencies, add a `[[tool.uv.ind ```toml [[tool.uv.index]] -# Optional, explicit name for the index. +# Optional name for the index. name = "pytorch" -# Required URL for the index. Expects a repository compliant with PEP 503 (the simple repository API). +# Required URL for the index. url = "https://download.pytorch.org/whl/cpu" ``` @@ -52,8 +52,8 @@ url = "https://download.pytorch.org/whl/cpu" ``` An index can be marked as `explicit = true` to prevent packages from being installed from that index -unless explicitly pinned to it. For example, to ensure that `torch` is _only_ installed from the -`pytorch` index, add the following to your `pyproject.toml`: +unless explicitly pinned to it. For example, to ensure that `torch` is installed from the `pytorch` +index, but all other packages are installed from PyPI, add the following to your `pyproject.toml`: ```toml [tool.uv.sources] diff --git a/docs/reference/cli.md b/docs/reference/cli.md index cae8a3e0245b0..a182d73d9b67f 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -142,14 +142,12 @@ uv run [OPTIONS]

This option is only available when running in a project.

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

Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

-

(Deprecated: use --index instead.)

-

May also be set with the UV_EXTRA_INDEX_URL environment variable.

--find-links, -f find-links

Locations to search for candidate distributions, in addition to those found in the registry indexes.

@@ -184,14 +182,12 @@ uv run [OPTIONS]
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --isolated

    Run the command in an isolated virtual environment.

    @@ -700,14 +696,12 @@ uv add [OPTIONS] >

    To add this dependency to an optional group in the current project instead, see --optional.

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

    Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

    -

    (Deprecated: use --index instead.)

    -

    May also be set with the UV_EXTRA_INDEX_URL environment variable.

    --find-links, -f find-links

    Locations to search for candidate distributions, in addition to those found in the registry indexes.

    @@ -742,14 +736,12 @@ uv add [OPTIONS] >
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

    @@ -1035,14 +1027,12 @@ uv remove [OPTIONS] ...

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

    May also be set with the UV_EXCLUDE_NEWER environment variable.

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

    Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

    -

    (Deprecated: use --index instead.)

    -

    May also be set with the UV_EXTRA_INDEX_URL environment variable.

    --find-links, -f find-links

    Locations to search for candidate distributions, in addition to those found in the registry indexes.

    @@ -1077,14 +1067,12 @@ uv remove [OPTIONS] ...
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

    @@ -1358,14 +1346,12 @@ uv sync [OPTIONS]

    Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.

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

    Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

    -

    (Deprecated: use --index instead.)

    -

    May also be set with the UV_EXTRA_INDEX_URL environment variable.

    --find-links, -f find-links

    Locations to search for candidate distributions, in addition to those found in the registry indexes.

    @@ -1400,14 +1386,12 @@ uv sync [OPTIONS]
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --inexact

    Do not remove extraneous packages present in the environment.

    @@ -1679,14 +1663,12 @@ uv lock [OPTIONS]

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

    May also be set with the UV_EXCLUDE_NEWER environment variable.

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

    Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

    -

    (Deprecated: use --index instead.)

    -

    May also be set with the UV_EXTRA_INDEX_URL environment variable.

    --find-links, -f find-links

    Locations to search for candidate distributions, in addition to those found in the registry indexes.

    @@ -1719,14 +1701,12 @@ uv lock [OPTIONS]
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

    @@ -1976,14 +1956,12 @@ uv export [OPTIONS]

    May be provided more than once.

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

    Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

    -

    (Deprecated: use --index instead.)

    -

    May also be set with the UV_EXTRA_INDEX_URL environment variable.

    --find-links, -f find-links

    Locations to search for candidate distributions, in addition to those found in the registry indexes.

    @@ -2028,14 +2006,12 @@ uv export [OPTIONS]
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

    @@ -2302,14 +2278,12 @@ uv tree [OPTIONS]

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

    May also be set with the UV_EXCLUDE_NEWER environment variable.

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

    Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

    -

    (Deprecated: use --index instead.)

    -

    May also be set with the UV_EXTRA_INDEX_URL environment variable.

    --find-links, -f find-links

    Locations to search for candidate distributions, in addition to those found in the registry indexes.

    @@ -2344,14 +2318,12 @@ uv tree [OPTIONS]
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --invert

    Show the reverse dependencies for the given package. This flag will invert the tree and display the packages that depend on the given package

    @@ -2691,14 +2663,12 @@ uv tool run [OPTIONS] [COMMAND]

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

    May also be set with the UV_EXCLUDE_NEWER environment variable.

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

    Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

    -

    (Deprecated: use --index instead.)

    -

    May also be set with the UV_EXTRA_INDEX_URL environment variable.

    --find-links, -f find-links

    Locations to search for candidate distributions, in addition to those found in the registry indexes.

    @@ -2733,14 +2703,12 @@ uv tool run [OPTIONS] [COMMAND]
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --isolated

    Run the tool in an isolated virtual environment, ignoring any already-installed tools

    @@ -2997,14 +2965,12 @@ uv tool install [OPTIONS]

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

    May also be set with the UV_EXCLUDE_NEWER environment variable.

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

    Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

    -

    (Deprecated: use --index instead.)

    -

    May also be set with the UV_EXTRA_INDEX_URL environment variable.

    --find-links, -f find-links

    Locations to search for candidate distributions, in addition to those found in the registry indexes.

    @@ -3039,14 +3005,12 @@ uv tool install [OPTIONS]
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

    @@ -3299,14 +3263,12 @@ uv tool upgrade [OPTIONS] ...

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

    May also be set with the UV_EXCLUDE_NEWER environment variable.

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

    Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

    -

    (Deprecated: use --index instead.)

    -

    May also be set with the UV_EXTRA_INDEX_URL environment variable.

    --find-links, -f find-links

    Locations to search for candidate distributions, in addition to those found in the registry indexes.

    @@ -3337,14 +3299,12 @@ uv tool upgrade [OPTIONS] ...
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

    @@ -4881,14 +4841,12 @@ uv pip compile [OPTIONS] ...

    Only applies to pyproject.toml, setup.py, and setup.cfg sources.

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

    Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

    -

    (Deprecated: use --index instead.)

    -

    May also be set with the UV_EXTRA_INDEX_URL environment variable.

    --find-links, -f find-links

    Locations to search for candidate distributions, in addition to those found in the registry indexes.

    @@ -4921,14 +4879,12 @@ uv pip compile [OPTIONS] ...
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

    @@ -5287,14 +5243,12 @@ uv pip sync [OPTIONS] ...

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

    May also be set with the UV_EXCLUDE_NEWER environment variable.

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

    Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

    -

    (Deprecated: use --index instead.)

    -

    May also be set with the UV_EXTRA_INDEX_URL environment variable.

    --find-links, -f find-links

    Locations to search for candidate distributions, in addition to those found in the registry indexes.

    @@ -5325,14 +5279,12 @@ uv pip sync [OPTIONS] ...
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

    @@ -5647,14 +5599,12 @@ uv pip install [OPTIONS] |--editable Only applies to pyproject.toml, setup.py, and setup.cfg sources.

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

    Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

    -

    (Deprecated: use --index instead.)

    -

    May also be set with the UV_EXTRA_INDEX_URL environment variable.

    --find-links, -f find-links

    Locations to search for candidate distributions, in addition to those found in the registry indexes.

    @@ -5685,14 +5635,12 @@ uv pip install [OPTIONS] |--editable unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

    @@ -6834,14 +6782,12 @@ uv venv [OPTIONS] [PATH]

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

    May also be set with the UV_EXCLUDE_NEWER environment variable.

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

    Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

    -

    (Deprecated: use --index instead.)

    -

    May also be set with the UV_EXTRA_INDEX_URL environment variable.

    --find-links, -f find-links

    Locations to search for candidate distributions, in addition to those found in the registry indexes.

    @@ -6872,14 +6818,12 @@ uv venv [OPTIONS] [PATH]
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

    @@ -7099,14 +7043,12 @@ uv build [OPTIONS] [SRC]

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

    May also be set with the UV_EXCLUDE_NEWER environment variable.

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

    Extra URLs of package indexes to use, in addition to --index-url.

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

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

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

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

    -

    (Deprecated: use --index instead.)

    -

    May also be set with the UV_EXTRA_INDEX_URL environment variable.

    --find-links, -f find-links

    Locations to search for candidate distributions, in addition to those found in the registry indexes.

    @@ -7137,14 +7079,12 @@ uv build [OPTIONS] [SRC]
  • unsafe-best-match: Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index
    • -
    --index-url, -i index-url

    The URL of the Python package index (by default: <https://pypi.org/simple>).

    +
    --index-url, -i index-url

    (Deprecated: use --default-index instead) The URL of the Python package index (by default: <https://pypi.org/simple>).

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

    The index given by this flag is given lower priority than all other indexes specified via the --extra-index-url flag.

    -

    (Deprecated: use --default-index instead.)

    -

    May also be set with the UV_INDEX_URL environment variable.

    --keyring-provider keyring-provider

    Attempt to use keyring for authentication for index URLs.

    diff --git a/docs/reference/settings.md b/docs/reference/settings.md index 03e7dd2c3c8aa..ff89d4e8be8ff 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -83,7 +83,8 @@ Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep Indexes are considered in the order in which they're defined, such that the first-defined index has the highest priority. Further, the indexes provided by this setting are given higher priority than any indexes specified via [`index_url`](#index-url) or -[`extra_index_url`](#extra-index-url). +[`extra_index_url`](#extra-index-url). uv will only consider the first index that contains +a given package, unless an alternative [index strategy](#index-strategy) is specified. If an index is marked as `explicit = true`, it will be used exclusively for those dependencies that select it explicitly via `[tool.uv.sources]`, as in: @@ -98,9 +99,9 @@ explicit = true torch = { index = "pytorch" } ``` -If an index is marked as `default = true`, it will be moved to the front of the list of -the list of indexes, such that it is given the highest priority when resolving packages. -Additionally, marking an index as default will disable the PyPI default index. +If an index is marked as `default = true`, it will be moved to the end of the prioritized list, such that it is +given the lowest priority when resolving packages. Additionally, marking an index as default will disable the +PyPI default index. **Default value**: `"[]"` @@ -646,7 +647,10 @@ Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep (the simple repository API), or a local directory laid out in the same format. Indexes are considered in the order in which they're defined, such that the first-defined -index has the highest priority. +index has the highest priority. Further, the indexes provided by this setting are given +higher priority than any indexes specified via [`index_url`](#index-url) or +[`extra_index_url`](#extra-index-url). uv will only consider the first index that contains +a given package, unless an alternative [index strategy](#index-strategy) is specified. If an index is marked as `explicit = true`, it will be used exclusively for those dependencies that select it explicitly via `[tool.uv.sources]`, as in: @@ -661,9 +665,9 @@ explicit = true torch = { index = "pytorch" } ``` -Marking an index as `default = true` will disable the PyPI default index and move the -index to the end of the prioritized list, such that it is used when a package is not found -on any other index. +If an index is marked as `default = true`, it will be moved to the end of the prioritized list, such that it is +given the lowest priority when resolving packages. Additionally, marking an index as default will disable the +PyPI default index. **Default value**: `"[]"` diff --git a/uv.schema.json b/uv.schema.json index b15d0f1c91874..f6ab2f8c57b46 100644 --- a/uv.schema.json +++ b/uv.schema.json @@ -148,7 +148,7 @@ } }, "index": { - "description": "The indexes to use when resolving dependencies.\n\nAccepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/) (the simple repository API), or a local directory laid out in the same format.\n\nIndexes are considered in the order in which they're defined, such that the first-defined index has the highest priority. Further, the indexes provided by this setting are given higher priority than any indexes specified via [`index_url`](#index-url) or [`extra_index_url`](#extra-index-url).\n\nIf an index is marked as `explicit = true`, it will be used exclusively for those dependencies that select it explicitly via `[tool.uv.sources]`, as in:\n\n```toml [[tool.uv.index]] name = \"pytorch\" url = \"https://download.pytorch.org/whl/cu121\" explicit = true\n\n[tool.uv.sources] torch = { index = \"pytorch\" } ```\n\nIf an index is marked as `default = true`, it will be moved to the front of the list of the list of indexes, such that it is given the highest priority when resolving packages. Additionally, marking an index as default will disable the PyPI default index.", + "description": "The indexes to use when resolving dependencies.\n\nAccepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/) (the simple repository API), or a local directory laid out in the same format.\n\nIndexes are considered in the order in which they're defined, such that the first-defined index has the highest priority. Further, the indexes provided by this setting are given higher priority than any indexes specified via [`index_url`](#index-url) or [`extra_index_url`](#extra-index-url). uv will only consider the first index that contains a given package, unless an alternative [index strategy](#index-strategy) is specified.\n\nIf an index is marked as `explicit = true`, it will be used exclusively for those dependencies that select it explicitly via `[tool.uv.sources]`, as in:\n\n```toml [[tool.uv.index]] name = \"pytorch\" url = \"https://download.pytorch.org/whl/cu121\" explicit = true\n\n[tool.uv.sources] torch = { index = \"pytorch\" } ```\n\nIf an index is marked as `default = true`, it will be moved to the end of the prioritized list, such that it is given the lowest priority when resolving packages. Additionally, marking an index as default will disable the PyPI default index.", "type": [ "array", "null" @@ -567,7 +567,7 @@ "type": "boolean" }, "explicit": { - "description": "Mark the index as explicit.\n\nExplicit indexes will _only_ be used when explicitly enabled via a `[tool.uv.sources]` definition, as in:\n\n```toml [[tool.uv.index]] name = \"pytorch\" url = \"https://download.pytorch.org/whl/cu121\" explicit = true\n\n[tool.uv.sources] torch = { index = \"pytorch\" } ```", + "description": "Mark the index as explicit.\n\nExplicit indexes will _only_ be used when explicitly requested via a `[tool.uv.sources]` definition, as in:\n\n```toml [[tool.uv.index]] name = \"pytorch\" url = \"https://download.pytorch.org/whl/cu121\" explicit = true\n\n[tool.uv.sources] torch = { index = \"pytorch\" } ```", "default": false, "type": "boolean" },