Documentation feedback

[zanieb]

This is a tracking issue for feedback on the new documentation at https://docs.astral.sh/uv/

[dmfigol]

https://docs.astral.sh/uv/concepts/python-versions/#adjusting-python-version-preferences
it is not clear with what subcommand i can use --python-preference only-managed to set it permanently.

[zanieb]

We don't have a commands to modify a persistent configuration file — you can put it in a uv.toml or pyproject.toml per

• https://docs.astral.sh/uv/configuration/files/
• https://docs.astral.sh/uv/reference/settings/#python-preference

Thanks for the feedback though! Sounds like we should link to the persistent configuration documentation here.

[shoucandanghehe]

A little suggestion: add the use of generate-shell-completion to First steps with uv

I habitually use --help to see what commands I can use.
Then I realized that there was no completion command, and didn't search for it until I want to open an issue!😝

PS: I don't understand why it should be hidden in --help. Except for this command, the outputs of help and --help are almost identical!

[zanieb]

I'm not sure why it's hidden — I copied this from Ruff. I think it might be because it shifts the indent for the rest of the commands way to the right and dramatically reduces the space we have for concise documentation.

Thanks for the feedback! Tracked in #6153

[zanieb]

Maybe we can improve the uvx to uv tool transition in the guide #6334 (comment)

[gusutabopb]

On getting-started/installation/#standalone-installer it says

When uv is installed via the standalone installer, self-updates are enabled

This sounded to me as if uv would automatically update itself (like many GUI apps do), but it seems this is not the case. I guess it just means uv self update is not available at all unless the standalone installer was used. I think wording here could be improved to clarify that.

By the way, I added this to my crontab to get auto-updates:

00 00 * * * uv self update

[minusf]

Minor confusion for me in https://docs.astral.sh/uv/concepts/tools/, emphasis mine:

Tools can also be installed with uv tool install, in which case their executables are available on the PATH — an isolated virtual environment is still used but it is not treated as disposable.

...

When running a tool with uvx or uv tool run, a virtual environment is stored in the uv cache directory and is treated as disposable.

For uv tool, the venv is, or is not treated as disposable?

Furthermore, what does it mean "disposable" in this context?

In my first reading I understood uvx only as a convenience alias to uv tool run. However they seem to create different types of venvs in different locations in different ways and I am not able to understand the difference after reading this concept page...

If I do uvx posting and uv tool install posting && uv tool run posting, what is the conceptual difference and which one should i use?

[prrao87]

Maybe we can improve the uvx to uv tool transition in the guide #6334 (comment)

One suggestion would be to reiterate in the CLI reference docs for uv tool run that it's also available as uvx. Users might end up there via google searches and not be aware that there's an alias.

Another thing is that in the tool concepts page, it directly references uvx in these ways:

Tools can be invoked without installation using uvx ...
When running a tool with uvx or uv tool run, a virtual environment is stored...

In both these cases, the implicit assumption is that the user knows that uvx is an alias for only uv tool run and that it invokes the tool instead of installing it (hence the x, rather than r, which is what one would intuitively think would be the alias). But the only way to know these distinctions is to have carefully read the tools guide section of the docs first, and not all users may end up on the guide page first and read things in the exact order they're shown in the sidebar 😅.

[zanieb]

(Thanks for the feedback everyone, I'll attempt to address all that)

We should talk about defining constraints in the pyproject.toml in the project concept per #6425

[zanieb]

@gusutabopb let me know if #6468 is sufficient!

@minusf and @prrao87 I've attempted to address those in:

• Further clarifications to the tools documentation #6474 and
• Clarify the uv tool run, uvx, and uv run relationships #6455

[alandelevieTR]

Hi! I hope this is the correct place, but I would request examples for:

Other indexes[#](https://docs.astral.sh/uv/#other-indexes)

uv is also known to work with JFrog's Artifactory, the Google Cloud Artifact Registry, and AWS Code Artifact.

I ask because this does not work from my existing pyproject.toml:

my-custom-package = {version = "0.0.5", source = "my-pip-repo-happens-to-be-gcp-artifact-registry"}
# ...

[[tool.poetry.source]]
name = "my-pip-repo-happens-to-be-gcp-artifact-registry"
url = "https://us-west2-python.pkg.dev/my-gcp-org/hello/simple/"
priority = "explicit"

I add auth to the config by running:

$ pip install keyring
$ pip install keyrings.google-artifactregistry-auth
$ gcloud auth application-default login
$ poetry config http-basic.my-pip-repo-happens-to-be-gcp-artifact-registry oauth2accesstoken "$(gcloud auth print-access-token)"

Finding the equivalent of that last line for uv is what has me stumped.

I'm similarly interested in jfrog examples, but this is the one I can provide the most specific details on.

[gusutabopb]

The FastAPI guide needs to be updated to reflect the changes introduced to the default behavior of uv init in version 0.4.0. The current docs still say a src -based layout would be created: https://docs.astral.sh/uv/guides/integration/fastapi/#initializing-a-fastapi-project

[devmcp]

uv can be installed on Windows using winget, but this isn't mentioned in the docs. Could/should it be added as an alternative installation method along with homebrew etc?

[alper]

I'm not sure why there's a python-version file if this information is also in the pyproject.toml.

[shunichironomura]

The documentation about running scripts using the inline metadata (link) doesn't mention support for specifying the dependency sources via the tool.uv.sources section, but it does seem to support it when I run, for example:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
# ]
# [tool.uv.sources]
# requests = { git = "https://github.com/psf/requests.git", tag = "v2.32.2" }
# ///

import requests

print(requests.__version__) # 2.32.2 (2.32.3 is the latest)

I think the documentation can be explicit about officially supporting (or not supporting) it.

[zanieb]

@shunichironomura thanks! I think we need to create a separate "Scripts" concept page because that's way too advanced for the "guide" documentation.

[scimas]

Would be nice to have information on whether virtual workspaces (no project and build-system sections in pyproject.toml?) like Cargo are supported.

[charliermarsh]

You might be looking for this: https://docs.astral.sh/uv/concepts/projects/#applications

[scimas]

That is still an application that has its own python code from what I can tell. The Cargo virtual workspaces just combine related packages together, where there isn't necessarily one "main" binary.

Taking from the workspace example in uv docs,

albatross
├── packages
│   ├── bird-feeder
│   │   ├── pyproject.toml
│   │   └── src
│   │       └── bird_feeder
│   │           ├── __init__.py
│   │           └── foo.py
│   ├──squirrel-feeder
│   │   ├── pyproject.toml
│   │   └── src
│   │       └── squirrel_feeder
│   │           ├── __init__.py
│   │           └── foo.py
│   └── seeds
│       ├── pyproject.toml
│       └── src
│           └── seeds
│               ├── __init__.py
│               └── bar.py
├── pyproject.toml
├── README.md
└── uv.lock

imagine bird-feeder and squirrel-feeder were equally important packages with the common seeds dependency.

And just to be clear, I'm not asking this feature to be implemented, only clarification on whether or not it is supported because the documentation page explicitly refers to Cargo.

[willmurphyscode]

I have a couple questions about the lockfile after reading the docs on it.

Is the uv.lock file specified anywhere? I looked at https://docs.astral.sh/uv/concepts/projects/#project-lockfile and expected to find a schema or a link to a schema or specification for what can go in uv.lock.

The reason I'm looking for a schema / specification is that I would like to be able to parse uv.lock files so that I can add a uv.lock parser Syft.

My other question is whether you expect the uv.lock file to remain stable, or whether there is planned work to change or extend its schema.

[astrojuanlu]

The Cargo virtual workspaces just combine related packages together, where there isn't necessarily one "main" binary.

@scimas Virtual projects were removed in #6720 (from the docs at least - cannot quickly find other pointers)

[charliermarsh]

@scimas -- Yeah that layout is fully supported. You can create a pyproject.toml at the root that is not itself linked to any Python code, and just lists workspace members and dependencies, i.e., a virtual workspace root as in Cargo.

@astrojuanlu -- We removed most mentions of "virtual" since it wasn't a familiar concept, but the idea of a project that just lists members and dependencies is still supported.

[nolanshah]

In addition to the poetry migration guide requested above, migration guides for pipenv, requirements.txt, and even direct from the environment would be helpful. It took too long to find that the -r requirements.txt semantics from pip install works with uv add.

Really a nit -- The concept pages are very in the weeds with details about the CLI. Being more opinionated on the patterns/anti-patterns of python project/dep/version/tool management with uv and focusing on concepts that influence user decisions (e.g. do I use ux tool or install a dev dependency) in the concepts guides would be helpful. Like for tools, the "Execution vs installation" section is the really critical "concept" there.

[astrojuanlu]

The "when (not) to use workspaces" section conflates

• Actual use cases for workspaces:

uv/docs/concepts/workspaces.md

Lines 152 to 165 in 94fc35e

	Workspaces are intended to facilitate the development of multiple interconnected packages within a
	single repository. As a codebase grows in complexity, it can be helpful to split it into smaller,
	composable packages, each with their own dependencies and version constraints.
	Workspaces help enforce isolation and separation of concerns. For example, in uv, we have separate
	packages for the core library and the command-line interface, enabling us to test the core library
	independently of the CLI, and vice versa.
	Other common use cases for workspaces include:
	- A library with a performance-critical subroutine implemented in an extension module (Rust, C++,
	etc.).
	- A library with a plugin system, where each plugin is a separate workspace package with a
	dependency on the root.

• Use cases not well suited for workspaces

uv/docs/concepts/workspaces.md

Lines 167 to 168 in 94fc35e

	Workspaces are _not_ suited for cases in which members have conflicting requirements, or desire a
	separate virtual environment for each member. In this case, path dependencies are often preferable.

It would be nice if the latter were more clearly explained, specifically the "independent/loosely related packages with possibly conflicting dependencies". The docs give an example of a "path dependency", but that seems to be targeted to a root member depending on a subpackage, which maybe isn't even needed. And the potential overlap with Dependency Groups is unclear.

Maybe a dedicated page (and, dare I say, another name?)

[bjornasm]

The dependencies are primarily specified in pyproject.toml, then uv sync updates uv.lock with the exact versions of what it installed. The uv.lock file is not meant to be manually edited.

My question was not how to edit the lock file, but how to let it dictate the dependencies of a project.

[charliermarsh]

I don't quite understand. The lockfile is created from the pyproject.toml. The pyproject.toml dictates the dependencies of the project; the lockfile is downstream of that.

[bjornasm]

@charliermarsh Thank you for taking the time, and sorry for creating confusion.

From the documentation:

Unlike the pyproject.toml which is used to specify the broad requirements of your project, the lockfile contains the exact resolved versions that are installed in the project environment. This file should be checked into version control, allowing for consistent and reproducible installations across machines.

I understand how this important for two reason, knowing the exact packages and version used for every commit in the project, and if anyone want to fork or clone a project and replicate the environment.

So say that I fork SomeRepo, that contains a uv.lock, to a new machine and want to have the exact resolved versions that was installed in the project environment by the creator of SomeRepo. How do I interact with uv.lock to replicate the project environment?

Reading the documentation it is described how uv.lock is generated (or how we avoid it to be changed), but it doesn't detail how uv.lock is used by uv. (Is there for instance a uv add uv.lock or uv init uv.lock)

[dylwil3]

So say that I fork SomeRepo, that contains a uv.lock, to a new machine and want to have the exact resolved versions that was installed in the project environment by the creator of SomeRepo. How do I interact with uv.lock to replicate the project environment?

Maybe uv sync --frozen is what you're looking for @bjornasm?

[TonyYanOnFire]

I think it would be better to have a chapter to introduce how to integrate uv into existing projects, or to improve the user experience of using uv to replace the tools it claims to replace.

Taking me as an example, I use pip/requirements.txt to maintain the dependencies of existing projects, use pyenv to manage multiple versions of Python interpreters, and use virtualenvwrapper to manage virtual environments. When I heard about the all-in-one tool uv, I was excited, but the next second I was frustrated: I had to figure out the details of UV to gradually replace these tools

Take this issue as an example to illustrate the challenges that new users of uv might encounter.

[Mapiarz]

If anybody is looking to get started with migrating from poetry to uv, I documented the approach I took here: #5200 (comment).

[bjornasm]

So say that I fork SomeRepo, that contains a uv.lock, to a new machine and want to have the exact resolved versions that was installed in the project environment by the creator of SomeRepo. How do I interact with uv.lock to replicate the project environment?

Maybe uv sync --frozen is what you're looking for @bjornasm?

Thank you, that seems what I am after!

[sh-shahrokhi]

Could you please provide information on the best way to install PyTorch with GPU support in a project that is portable across different systems and can be easily upgraded?

[GiovanniGiacometti]

Hi guys, I just wanted to report that the Discord invitation link provided here in the documentation is expired.

[Muzych]

As a Chinese language user, I would like to inquire whether the UV community's documentation requires internationalization translation, and I am willing to contribute a Pull Request for the Chinese translation of the UV documentation.

[zanieb]

Hey @GiovanniGiacometti — that link works for me still, are you sure?

@Muzych I appreciate the offer! I'm not quite sure how we'd maintain that — we make frequent changes to the documentation. What do you think the long-term plan for that would be?

[Muzych]

Hey @GiovanniGiacometti — that link works for me still, are you sure?嘿——那个链接对我来说还能用，你确定吗？

@Muzych I appreciate the offer! I'm not quite sure how we'd maintain that — we make frequent changes to the documentation. What do you think the long-term plan for that would be?我感谢您的提议！我不太确定我们该如何维护——我们的文档经常变动。您认为这方面的长期计划会是什么样的呢？

Hello, my idea is to first complete the internationalization translation based on the current version, and then make minor adjustments to the details once UV's performance is stable. What do you think about this approach?

[tekumara]

A surprising behaviour I've noticed, that I couldn't see documented and possibly good to capture somewhere:

uv sync creates and uses .venv in the parent directory, when the parent directory contains pyproject.toml, and even if the current directory also has a pyproject.toml.

[zanieb]

uv sync creates and uses .venv in the parent directory, when the parent directory contains pyproject.toml, and even if the current directory also has a pyproject.toml.

I think this should only be the case if the current directory is a workspace member of the parent directory.

[zanieb]

Hello, my idea is to first complete the internationalization translation based on the current version, and then make minor adjustments to the details once UV's performance is stable. What do you think about this approach?

We'll be making large, frequent adjustments to the documentation. I'm concerned it will go out of date. Let's discuss this over in a dedicated issue #9606

[tekumara]

I think this should only be the case if the current directory is a workspace member of the parent directory.

In my case I hadn’t set up a workspace.

[zanieb]

@tekumara that sounds like a bug, could you open an issue with a reproduction?

[abitrolly]

https://docs.astral.sh/uv/guides/scripts/ doesn't explain where uv creates environments and how to clean up them after.

[eliasdabbas]

Hello,

I came across a broken link while reading the documentation, so I thought I'd crawl the whole site to check.

The following are 404 pages:

• url: Where the broken link is located
• link: The URL of the broken link
• text: The anchor text, just to make it easier to find the link on the page

	url	link	text
0	https://astral.sh/blog/ruff-v0.5.0#changes-to-e999-and-reporting-of-syntax-errors	https://docs.astral.sh/ruff/rules/open-sleep-or-subprocess-in-async-function/	open-sleep-or-subprocess-in-async-function
1	https://astral.sh/blog/ruff-v0.5.0#changes-to-e999-and-reporting-of-syntax-errors	https://astral.sh/blog/%60https:/docs.astral.sh/ruff/rules/blocking-os-call-in-async-function/%60	blocking-os-call-in-async-function
2	https://astral.sh/blog/ruff-v0.5.0#changes-to-e999-and-reporting-of-syntax-errors	https://docs.astral.sh/ruff/rules/trio-async-function-with-timeout/	trio-async-function-with-timeout
3	https://astral.sh/blog/ruff-v0.5.0#changes-to-e999-and-reporting-of-syntax-errors	https://docs.astral.sh/ruff/rules/trio-unneeded-sleep/	trio-unneeded-sleep
4	https://astral.sh/blog/ruff-v0.5.0#changes-to-e999-and-reporting-of-syntax-errors	https://docs.astral.sh/ruff/rules/trio-zero-sleep-call/	trio-zero-sleep-call
5	https://astral.sh/blog/ruff-v0.5.0#changes-to-e999-and-reporting-of-syntax-errors	https://docs.astral.sh/ruff/rules/misplaced-bare-raise%60/	misplaced-bare-raise
6	https://astral.sh/blog/ruff-v0.0.276	https://astral.sh/blog/settings.md#include	include
7	https://docs.astral.sh/uv/reference/build_failures/	https://docs.astral.sh/uv/pip/compatibility.md#pep-517-build-isolation	build isolation by default
8	https://docs.astral.sh/uv/reference/build_failures/	https://docs.astral.sh/uv/reference/settings.md#dependency-metadata	provide dependency metadata manually
9	https://astral.sh/blog/ruff-v0.2.0	https://docs.astral.sh/ruff/rules/trio-timeout-without-await	trio-timeout-without-await
10	https://astral.sh/blog/ruff-v0.2.0	https://docs.astral.sh/ruff/rules/trio-async-function-with-timeout	trio-async-function-with-timeout
11	https://astral.sh/blog/ruff-v0.2.0	https://docs.astral.sh/ruff/rules/trio-unneeded-sleep	trio-unneeded-sleep
12	https://astral.sh/blog/ruff-v0.2.0	https://docs.astral.sh/ruff/rules/trio-zero-sleep-call	trio-zero-sleep-call

Code to reproduce (or if you want to run this periodically):

import advertools as adv
import pandas as pd


adv.crawl(
    url_list="https://astral.sh/",
    output_file="astral.jsonl",
    follow_links=True)


crawldf = pd.read_json("astral.jsonl", lines=True)

error_urls = crawldf[crawldf['status'].ne(200)]['url']
linksdf = adv.crawlytics.links(df)

linksdf[linksdf['link'].isin(error_urls)]

Thanks!

[zanieb]

@abitrolly that's beyond the scope of the a "guide", when we introduce a "concept" document for scripts we can cover that — but they're just in the uv cache.

[zanieb]

@eliasdabbas cool thank you! cc @dhruvmanila for Ruff's documentation.

[abitrolly]

@zanieb it still may worth to mention it somewhere in the middle, or link to relevant cleanup docs. I assume uv users are advanced enough to care.

[depau]

Hi! I noticed the documentation about configuring alternative indexes seems to be outdated and incomplete: https://docs.astral.sh/uv/guides/integration/alternative-indexes/

• It doesn't mention anything about [[tool.uv.index]] settings, which are useful
• In Environment variables, UV_EXTRA_INDEX_URL is said to be deprecated, but in the alternative indexes page it is used.

Also the Environment variables page doesn't explain how to properly authenticate to alternative indexes other than embedding the credentials in the URL

Have a good day!