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.

[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!

[hrmnjt]

First, thanks for uv and ever growing documentation.

I was reading Versioning Policy (https://docs.astral.sh/uv/reference/policies/versioning/) document and was unable to visualize what would be needed for 1.0 stable APIs. Is it possible to write (10000 ft. level) bullet points which explain the path to 1.0 for uv?

[eliasdabbas]

I found a broken link here:

	url	link	text	nofollow
0	https://astral.sh/blog/ruff-v0.2.0	https://docs.astral.sh/ruff/rules/non-pep604-annotation	non-pep604-annotation	False

Crawling the whole site doesn't take long (~40 seconds).

In case you want to run this periodically:

uv run https://gist.githubusercontent.com/eliasdabbas/681c9c7a3d1c00512c665bd4415ac52b/raw/79403412daceb86c2a9839855bccdad67e86277c/uv_docs_broken_links.py

Gist: https://gist.github.com/eliasdabbas/681c9c7a3d1c00512c665bd4415ac52b

Thanks again for all the great work.

[zanieb]

@depau thanks!

It doesn't mention anything about [[tool.uv.index]] settings, which are useful

That's on the todo-list, e.g., #9867.

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

Authenticating with credentials outside the URL is at https://docs.astral.sh/uv/configuration/environment/#uv_index_name_password — but this is just a reference document it isn't likely to have further exposition.

@hrmnjt

I was reading Versioning Policy (https://docs.astral.sh/uv/reference/policies/versioning/) document and was unable to visualize what would be needed for 1.0 stable APIs. Is it possible to write (10000 ft. level) bullet points which explain the path to 1.0 for uv?

We don't have a plan for this yet. We're not really in a rush to reach 1.0. I think there's not really a list of things we need to do before we switch to 1.0, it's more like we want the tool to be in the world for a while so we can fix rough edges and iterate quickly.

@eliasdabbas Thank you!

[abitrolly]

@eliasdabbas I like the Python version of the link checker. Definitely useful. Would be interested to see how it compares to Rust based https://lychee.cli.rs/

[eliasdabbas]

@abitrolly I'm not familiar with Lychee, but I just took a look. Based on what I saw so far:

Pros: It can check links in a tree locally, supports .md .rst and HTML. This makes it great for pre-commit checks/hooks.

Cons: It doesn't support recursive crawling of websites, which includes discovering links, following them, redirects, etc.

Python pros: Supports recursive crawling with customizable rules, and can be as fast as you want it to be.

Python cons: Does not support .md or .rst.

So if you want the actual live website the advertools/Python solution seems better, if you want to check .md or .rst files, it seems Lychee is the good choice. Again I'm not that familiar with it, so take what I said with a grain of salt.

[carrollpaul]

When I build and run the container from the Docker example as-is, I get this error:

Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create fa
iled: runc create failed: unable to start container process: exec: "fastapi": executable file not found in $PATH: 
unknown

[zanieb]

@carrollpaul I tested that just now and cannot reproduce. Please open an issue with a reproduction.

[clbarnes]

The docs for deploying a zip archive for AWS lambda ( https://docs.astral.sh/uv/guides/integration/aws-lambda/#deploying-a-zip-archive ) includes the usage of uv pip install's --no-installer-metadata argument; that doesn't seem to exist https://docs.astral.sh/uv/reference/cli/#uv-pip-install

[charliermarsh]

It exists, it's just not visible on the CLI. It's analogous to: https://docs.astral.sh/uv/configuration/environment/#uv_no_installer_metadata.

[judgewooden]

I have switched to uv for most of my projects and am wondering if there is an easy way to create a snapshot of the environment. I need to experiment with upgrades and dependencies, and if things go wrong, revert to the original snapshot.

In the past, I used pip freeze > requirements-pre-upgrade.txt before making changes. I know I can do the same with uv pip freeze, but I was curious if there is a better way to handle this using uv tools.

[debnath-d]

I need to experiment with upgrades and dependencies, and if things go wrong, revert to the original snapshot.

In the past, I used pip freeze > requirements-pre-upgrade.txt before making changes. I know I can do the same with uv pip freeze, but I was curious if there is a better way to handle this using uv tools.

@judgewooden

All information is contained in pyproject.toml and uv.lock. Just backup these two files.

If things go wrong, replace these files with the backed up files and run uv sync.

[edmorley]

Some misc docs feedback before I forget...

Locking and syncing concepts page

If I search the docs for "sync", the top result is the "Locking and Syncing" concepts page:
https://docs.astral.sh/uv/concepts/projects/sync/

The page has "syncing" in the title and "sync" in the URL, but the page content itself really only seems to be about locking rather than syncing, which was surprising - since I was hoping to find more about uv sync?

uv sync CLI reference docs hidden in search results

After not finding what I was after on the "Locking and Syncing" concepts page, I tried searching for "sync" again, hoping to find the uv sync CLI reference docs (ie: https://docs.astral.sh/uv/reference/cli/#uv-sync).

However, instead the search results preview highlights some of the uv pip usage docs instead (with the uv sync content being hidden under the "9 more on this page" collapsed section).

eg:

I'm presuming this is mostly due to the way mkdocs/its search plugin is designed, so I don't know if there is much that can be done (other than eg splitting CLI command pages up into smaller chunks?), and now I know to check the collapsed sections I can work around it - but I imagine this may hinder docs discovery for others too?

Clarifying the difference between python-downloads and python-preference

As part of deciding which uv sync arguments I should use in our build scripts, I read through the CLI command reference docs here:
https://docs.astral.sh/uv/reference/cli/#uv-sync

I knew I wanted to ensure uv always used our own Python distribution, rather than downloading a uv-managed installation - however, at first glance it wasn't immediately apparent whether I should be using python-downloads, python-preference, or both. (ie: Part of that uncertainty was wondering whether one option was a superset of the other, or if they were orthogonal.)

I was able to work it out after using doc search to find other pages like these:
https://docs.astral.sh/uv/concepts/python-versions/#disabling-automatic-python-downloads
https://docs.astral.sh/uv/concepts/python-versions/#adjusting-python-version-preferences

...but I wonder if the following might help:
(a) some backlinks from the reference pages back to the concepts sections (both the CLI reference usage docs, and the settings reference docs)
(b) A half-sentence or so added to both sections on the concept page explaining how they interact

Understanding what uv sync installs by default

When reading https://docs.astral.sh/uv/reference/cli/#uv-sync it wasn't immediately clear to me what dependency groups if any would be installed by default.

For example, the intro for the uv sync command doesn't mention what it installs, and none of the CLI args like --all-groups and related hint at it. From seeing the --no-dev arg I was able to infer that dev dependencies might be installed by default, but I had to search the docs manually to find:
https://docs.astral.sh/uv/concepts/projects/dependencies/#development-dependencies
https://docs.astral.sh/uv/concepts/projects/dependencies/#default-groups

I think some backlinks from the CLI args to the concepts docs would similarly help in this case.

General docs discoverability/navigation/ordering

I think several of the issues above only occurred because:

1. I had skipped over some of the concept docs and used the CLI command reference docs as my starting point.
2. The CLI reference docs don't tend to backlink to the other parts of the docs.

I'm normally someone that fully reads docs from the start/intro - I think part of the reason I skipped ahead was due to the volume of the docs (eg number of sections listed in the sidebar), and some of the earlier docs sections being less relevant to me (eg running scripts, manually managing Python installations, installing/running tools).

I don't think the volume of docs can really be avoided (uv does a lot, and comprehensive docs are needed/worthwhile), but I wonder if some re-ordering or adjusting of the initial intro/sections might help? For example, to me uv sync is uv's bread and butter use-case, but yet it's mentioned quite late in the intro (I think this might have been part of the person's issue in #10813 too?).

I also think the size of the docs means that backlinks from one-section to another (particularly CLI reference -> concepts) are particularly important for ensuring people end up in the right place if their initial entry-point to the docs wasn't ideal (eg an experienced user who jumps ahead to the CLI reference section, or if a search engine deep links to a reference page etc).

Anyway, thank you for having put so much time into docs already - hope the above was helpful (I know it's hard to get fresh eyes back on content with which you're already familiar).

[debnath-d]

Perhaps it would be a good idea to point this out: https://docs.astral.sh/uv/reference/settings/#find-links on this page: https://docs.astral.sh/uv/configuration/indexes ?

@zanieb

[charliermarsh]

That’s awesome feedback, thanks @edmorley.