Support using `--index` to refer to index names by EliteTK · Pull Request #17455 · astral-sh/uv

EliteTK · 2026-01-13T23:35:35Z

Summary

Implement #13974.

Some of the code was inspired by existing code from uv_distribution::metadata::lowering which handles resolving index name references within pyproject.toml.

This PR adds a new IndexArg type to uv_distribution_types which holds information about an index as passed on the CLI. Specifically the current Index type has a non-optional url field. IndexArg solves this by including two variants, one for the Index type and one for an UnresolvedIndex which holds the IndexName. This means that all the CLI handling can use IndexArg and then the standard resolve functions can transform these IndexArgs into Indexes. This allows you to reference indexes by name if they are already defined somewhere else.

Currently support for --default-index by name is not included.

Error handling

The initial code made use of Result to propagate errors regarding resolution (i.e. no index found for that name). But I added a commit which replaces this with an early exit(2) as that seems to be the style used by other resolve style code.

The new `Resolve` trait

PipOptions required a bunch of changes as it was using the From trait initially but index resolution requires additional metadata for the names which could have been passed as a tuple except for the fact that it's ugly and also breaks the orphan rule so it wasn't actually an option. Another alternative would be to do the resolution earlier but that seemed like an excessive amount of boilerplate, so instead a new trait was used.

Argument cross-references

You can't resolve an index which you passed on the CLI (e.g. --index foo=bar --index foo) as I felt that didn't make sense as a feature even if it could have been supported. Maybe there is a use for it though? Not sure.

To Do

Index priority - it's still using the resolution priority which means that indexes can only come from the workspace pyproject.toml in workspaces. I haven't finished figuring out the best way to get this working yet.
Index writeback - Once index priority is working, the Workspace origin will be used here and indexes with Project or Workspace origin won't get written back.

`uv tool`

Passing --index to uv tool even if it's the only index doesn't guarantee that it will use only that index for the tool. Moreover, due to the fact that --index <name> works identically to --index <name>=..., the side effect is that the index will appear twice in the uv-receipt.toml. I think that any changes in this area are probably outside of the scope of this change.

Test Plan

Tests currently need updating and changing to deal with the other changes to this PR.

EliteTK · 2026-01-15T19:38:08Z

crates/uv/tests/it/edit.rs

+    uv_snapshot!(filters, context.add().arg("iniconfig").arg("--index").arg("test-index").current_dir(&child_dir), @r"
+    success: false
+    exit_code: 2
+    ----- stdout -----
+
+    ----- stderr -----
+    error: Request failed after 3 retries
+      Caused by: Failed to fetch: `http://[LOCALHOST]/iniconfig/`
+      Caused by: HTTP status server error (503 Service Unavailable) for url (http://[LOCALHOST]/iniconfig/)
+    ");
+
+    //let lock = fs_err::read_to_string(context.temp_dir.join("uv.lock"))?;
+    //insta::with_settings!({
+    //    filters => filters,
+    //}, {
+    //    assert_snapshot!(lock, @r#"
+    //"#);
+    //});


Need to investigate what happens if you don't pass --index.

So, I am going to leave this as is for now.

Although I think there's an argument to be made that if you're adding an index and it matches identically an index in the workspace (regardless of if you used the name, or spelled it out) that maybe we shouldn't mirror it in the child.

But the way things like #17610 work seems like maybe justification for leaving it as is.

Can you remove the commented out code, and/or leave a TODO comment?

EliteTK · 2026-01-15T19:39:01Z

crates/uv/tests/it/edit.rs

+        [[tool.uv.index]]
+        name = "test-index"
+        url = "https://pypi-proxy.fly.dev/simple"


I am not sure if we want this. But also, need to check what happens normally.

Okay, so index name references in [tool.uv.sources] are resolved in "project" then "workspace" order.

But when it comes to picking an index to use for a package without a specified source, we pick "workspace" then "project".

I'm not really sure what the correct answer is here. I'm going to leave it as is for now...

I'd prefer workspace root only, to avoid the problem of workspace root and member declaration getting out of sync.

@konstin you'd prefer workspace root only in what sense?

Isn't @EliteTK describing an existing behavior?

konstin · 2026-01-20T09:22:55Z

crates/uv/tests/it/edit.rs

+    let filters: Vec<_> = context
+        .filters()
+        .into_iter()
+        .chain([(r"http://127\.0\.0\.1:\d+", "[PARENT_INDEX]")])


nit: regex::escape the mock server URL - though that filter doesn't seem to be used?

konstin · 2026-01-20T09:29:15Z

crates/uv/tests/it/edit.rs

+    uv_snapshot!(filters, context.add().arg("iniconfig").arg("--index").arg("test-index").current_dir(&child_dir), @r"
+    success: false
+    exit_code: 2
+    ----- stdout -----
+
+    ----- stderr -----
+    error: Request failed after 3 retries
+      Caused by: Failed to fetch: `http://[LOCALHOST]/iniconfig/`
+      Caused by: HTTP status server error (503 Service Unavailable) for url (http://[LOCALHOST]/iniconfig/)
+    ");
+
+    //let lock = fs_err::read_to_string(context.temp_dir.join("uv.lock"))?;
+    //insta::with_settings!({
+    //    filters => filters,
+    //}, {
+    //    assert_snapshot!(lock, @r#"
+    //"#);
+    //});


Can you remove the commented out code, and/or leave a TODO comment?

zanieb · 2026-01-21T16:25:01Z

Moreover, due to the fact that --index works identically to --index =..., the side effect is that the index will appear twice in the uv-receipt.toml

This seems problematic?

zanieb · 2026-01-21T16:25:46Z

This means that if you reference a workspace index in a package add command, it will get copied to the package. This behaviour matches what would happen if you pass the full index including a name. I wasn't completely sure what to do here, but I feel as if it might be confusing to have them behave differently.

Is it necessary for it to be copied into the child package? Or if you added it to the child package without doing so would the parent index still be used properly?

zanieb · 2026-01-21T16:27:37Z

When resolving the name of an index within a pyproject.toml, the lowering code resolves it by looking at the current file first, and then the workspace file.

On the other hand, when resolving which index to use for a package which has no specified index, the resolution takes the workspace index first and then the package's indexes next.

So --name resolves to an index in the opposite order in which index priority is applied during resolution?

EliteTK · 2026-01-21T17:09:11Z

Moreover, due to the fact that --index works identically to --index =..., the side effect is that the index will appear twice in the uv-receipt.toml

This seems problematic?

This doesn't cause any issues at the moment but we could de-duplicate things such that only the first index for each unique URL is kept in the order they would have been kept before. I don't think the name is itself used for anything? That being said, this seems like an issue with how uv tool install works as you can also replicate the same receipt (with a duplicate entry) in other ways.

I'm happy to fix it though, do you want me to do it as part of this PR?

This means that if you reference a workspace index in a package add command, it will get copied to the package. This behaviour matches what would happen if you pass the full index including a name. I wasn't completely sure what to do here, but I feel as if it might be confusing to have them behave differently.

Is it necessary for it to be copied into the child package? Or if you added it to the child package without doing so would the parent index still be used properly?

It's definitely an option not to add it to the child package. The right index will be picked up as the name resolution order is project then workspace, so if the project doesn't have an index with that name, the workspace one will be picked.

But there is this issue: #17610, which is somewhat related.

I feel that if we were to fix this, we should fix this in a way which is agnostic to whether the index was mentioned by name, or fully written out with a conflicting name. Although we can also just mark the index as having originated by name and then not write it back in those situations. But we have to be careful as you can specify a --default-index by name but the original index may have been a non-default one, in which case it would be wrong to not write it back.

When resolving the name of an index within a pyproject.toml, the lowering code resolves it by looking at the current file first, and then the workspace file.
On the other hand, when resolving which index to use for a package which has no specified index, the resolution takes the workspace index first and then the package's indexes next.

So --name resolves to an index in the opposite order in which index priority is applied during resolution?

No, --index <name> resolves in the order of index priority during resolution, which I felt made sense initially, but the approach used by the lowering code (still uses priority, but it puts package indexes in front of the workspace indexes, which is the reverse) also makes sense.

zanieb · 2026-01-21T17:39:32Z

@EliteTK can we ship this under a preview flag so we don't need to wait until 0.10 to merge?

zanieb · 2026-01-21T17:40:17Z

No, --index resolves in the order of index priority during resolution, which I felt made sense initially, but the approach used by the lowering code (still uses priority, but it puts package indexes in front of the workspace indexes, which is the reverse) also makes sense.

I don't understand how to reconcile this comment with your original one?

zanieb · 2026-01-21T17:44:25Z

crates/uv-cli/src/options.rs

+/// Resolve [`IndexArg`]s into [`Index`]es using indexes defined on the
+/// filesystem and combine the `default_index` and `index` into one vector.


I think this could be a bit less descriptive of the code and more of the intent? LIke

Suggested change

/// Resolve [`IndexArg`]s into [`Index`]es using indexes defined on the

/// filesystem and combine the `default_index` and `index` into one vector.

/// Resolve index options into a prioritized list of [`Index`].

///

/// Index name references are resolved to index URLs using values from the file system.

///

/// The default index is placed after all other indexes.

zanieb · 2026-01-21T17:45:15Z

crates/uv-cli/src/options.rs

+            Err(error) => {
+                eprintln!("error: {error}");
+                std::process::exit(2);
+            }


Do you know why we do this in the other code? It's pretty janky. It doesn't respect our Printer, it doesn't print the error chain, etc.

EliteTK · 2026-01-21T17:54:45Z

@EliteTK can we ship this under a preview flag so we don't need to wait until 0.10 to merge?

Yeah, no objections here.

No, --index resolves in the order of index priority during resolution, which I felt made sense initially, but the approach used by the lowering code (still uses priority, but it puts package indexes in front of the workspace indexes, which is the reverse) also makes sense.

I don't understand how to reconcile this comment with your original one?

I will adjust it for clarity, but the section you referenced mentions that this PR uses the "second strategy" which refers to:

"On the other hand, when resolving which index to use for a package which has no specified index, the resolution takes the workspace index first and then the package's indexes next."

zanieb · 2026-01-21T18:15:17Z

crates/uv-distribution-types/src/index.rs

+pub struct ResolveIndexArgError(IndexName);
+
+impl IndexArg {
+    /// Parse an Index passed on the command line


Suggested change

/// Parse an Index passed on the command line

/// Parse an index passed on the command line

zanieb · 2026-01-21T18:16:05Z

crates/uv-distribution-types/src/index.rs

+        }
+    }
+
+    pub fn try_resolve<I>(self, indexes: I) -> Result<Index, ResolveIndexArgError>


This could probably use a doc comment

zanieb · 2026-01-21T18:17:14Z

crates/uv-settings/src/settings.rs

        })
    }
+
+    pub fn indexes(&self) -> impl Iterator<Item = Index> {


This should probably have a doc comment

zanieb · 2026-01-21T18:17:32Z

crates/uv-settings/src/settings.rs

+        self.index
+            .iter()
+            .flatten()
+            .cloned()


Do we need to clone? Can the caller clone?

zanieb · 2026-01-21T18:18:23Z

crates/uv/tests/it/edit.rs

    ----- stderr -----
-    warning: Relative paths passed to `--index` or `--default-index` should be disambiguated from index names (use `[PREFIX]test-index`). Support for ambiguous values will be removed in the future
-    error: Directory not found for index: file://[TEMP_DIR]/test-index
+    error: Could not find an index named `test-index`


We might want a follow-up issue to enumerate searched source files here.

zanieb · 2026-01-21T18:19:19Z

crates/uv/tests/it/edit.rs

-    warning: Relative paths passed to `--index` or `--default-index` should be disambiguated from index names (use `[PREFIX]test-index`). Support for ambiguous values will be removed in the future
-    error: Directory not found for index: file://[TEMP_DIR]/test-index


Have we considered continuing to support the current behavior if ./test-index exists and / or if the name test-index doesn't exist?

I hadn't, but I would say it should be only if the directory exists and the index doesn't. Otherwise you're going to get a confusing error whenever you mis-type an index or mis-type a directory name.

But honestly I am mildly against this kind of special casing.

Rather simple to implement though.

I think such special casing generally makes transitioning easier because then the change is breaking for less people? I don't think it's an ideal end state, but the mistake was when we allowed foo to be treated as a relative path without ./foo in the first place.

zanieb · 2026-01-21T18:25:25Z

This will need some documentation updates, which might help explain the behavior?

The code looks fine but I only sort of understand how behaves, tbh.

It's only used by the cli parsing, and involves a silly destructuring/restructuring dance to set the `default` field. Making it a function also avoids needing to explicitly set the origin.

Original code by Zanie with the temporary jury-rigging done by Tom.

These aren't used since IndexArg must only originate from the CLI.

…ndex-name only.

We _could_ print the index name before resolution but the goal here isn't to verify the integrity of the resolve function (to ensure that it did actually do the equality comparison) but rather just to troubleshoot which index it resolved to (in which case the name is embedded in the final index).

EliteTK temporarily deployed to uv-test-registries January 13, 2026 23:40 — with GitHub Actions Inactive

EliteTK force-pushed the tk/index-by-name branch 3 times, most recently from 747f88f to 6355b20 Compare January 15, 2026 19:35

EliteTK commented Jan 15, 2026

View reviewed changes

EliteTK force-pushed the tk/index-by-name branch 2 times, most recently from 4c9003d to a4070c9 Compare January 19, 2026 15:15

EliteTK marked this pull request as ready for review January 19, 2026 15:16

EliteTK requested a review from konstin January 19, 2026 15:16

EliteTK force-pushed the tk/index-by-name branch from a4070c9 to d5df9b1 Compare January 19, 2026 16:09

konstin approved these changes Jan 20, 2026

View reviewed changes

konstin requested a review from zanieb January 20, 2026 09:30

zanieb added the breaking A breaking change label Jan 21, 2026

zanieb added this to the v0.10.0 milestone Jan 21, 2026

zanieb reviewed Jan 21, 2026

View reviewed changes

crates/uv-settings/src/settings.rs

self.index

.iter()

.flatten()

.cloned()

Copy link

Member

zanieb Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to clone? Can the caller clone?

zanieb reviewed Jan 21, 2026

View reviewed changes

EliteTK force-pushed the tk/index-by-name branch from d5df9b1 to 7c062e1 Compare January 30, 2026 14:26

EliteTK marked this pull request as draft January 30, 2026 14:32

EliteTK force-pushed the tk/index-by-name branch from 7c062e1 to 56472a1 Compare February 3, 2026 22:07

EliteTK and others added 8 commits February 5, 2026 13:16

Replace impl FromStr for Index with Index::from_cli

f732eb0

It's only used by the cli parsing, and involves a silly destructuring/restructuring dance to set the `default` field. Making it a function also avoids needing to explicitly set the origin.

Use Index::with_origin where possible

a81bdf6

Add an IndexArg type to allow unresolved index arguments

1bc9d97

Original code by Zanie with the temporary jury-rigging done by Tom.

impl FromStr for IndexArg

e58eb29

Basic --index by name support

46d9c71

Just exit during index resolution to avoid the Result mess

0e82777

Basic test case

1b31f75

More tests

f767ead

EliteTK force-pushed the tk/index-by-name branch from 56472a1 to 492db42 Compare February 5, 2026 13:21

EliteTK temporarily deployed to uv-test-publish February 5, 2026 14:23 — with GitHub Actions Inactive

EliteTK added 12 commits February 5, 2026 15:13

Document new --index <name> behaviour

217d198

Remove support for --default-index <name>

28ef2ef

Remove serialisation and schema support from IndexArg

8fee70c

These aren't used since IndexArg must only originate from the CLI.

Implement IndexArgStrategy to configure between directory-first and i…

56a11fc

…ndex-name only.

Preview feature alternative resolution

a414ee0

Some additional comments

5ba6ba5

Fix origin tracking on indexes

85ec937

Only add necessary indexes into pyproject.toml

99abf15

prioritize package indexes when a package is specified

a0bb31b

Add workspace test

5cde61a

Test name changes

ce7e763

EliteTK force-pushed the tk/index-by-name branch from 06d4b10 to ce7e763 Compare February 5, 2026 15:13

EliteTK added 3 commits February 5, 2026 16:34

Tests for sync, run, and lock

8f7d326

Adjust CLI documentation

3e03b6b

More sophisticated precedence testing

4a9ee7f

		/// Resolve [`IndexArg`]s into [`Index`]es using indexes defined on the
		/// filesystem and combine the `default_index` and `index` into one vector.

-/// Resolve [`IndexArg`]s into [`Index`]es using indexes defined on the
-/// filesystem and combine the `default_index` and `index` into one vector.
+/// Resolve index options into a prioritized list of [`Index`].
+///
+/// Index name references are resolved to index URLs using values from the file system.
+///
+/// The default index is placed after all other indexes.

	/// Parse an Index passed on the command line
	/// Parse an index passed on the command line

		warning: Relative paths passed to `--index` or `--default-index` should be disambiguated from index names (use `[PREFIX]test-index`). Support for ambiguous values will be removed in the future
		error: Directory not found for index: file://[TEMP_DIR]/test-index

Conversation

EliteTK commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Error handling

The new Resolve trait

Argument cross-references

To Do

uv tool

Test Plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zanieb commented Jan 21, 2026

Uh oh!

zanieb commented Jan 21, 2026

Uh oh!

zanieb commented Jan 21, 2026

Uh oh!

EliteTK commented Jan 21, 2026

Uh oh!

zanieb commented Jan 21, 2026

Uh oh!

zanieb commented Jan 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

EliteTK commented Jan 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zanieb commented Jan 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

EliteTK commented Jan 13, 2026 •

edited

Loading

The new `Resolve` trait

`uv tool`