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.

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

[cmsirbu]

I'm having some difficulty with the Build Systems as a new uv user converting a project from poetry. So Poetry has its own build backend, which means I've never had to choose and this is where I think the docs could be more helpful.

Right now, the docs are explaining what a build system does for you and mentions that you can choose one with a parameter to uv init, but otherwise sends you to undefined external docs for your chosen build system (works only if you know what to choose in the first place). Some questions arise here:

• What should I choose? If there's an opinionated default, docs should guide me towards setting it up correctly.
• Do I need to install it alongside uv or does it manage that for me?
• What happens if I don't define it or have an incompatible build-backend defined (e.g. migrating from Poetry).

And because I'm still in poetry/uv limbo, I have this still defined, but uv build seems to work fine despite not explicitly supporting Poetry as a backend. Not trying to turn this into a migration guide, but just to reinforce the questions above.

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

> uv build
Building source distribution...
Building wheel from source distribution...
Successfully built dist/mkdocs_ansible_collection-0.2.1.tar.gz
Successfully built dist/mkdocs_ansible_collection-0.2.1-py3-none-any.whl

[zanieb]

uv supports all build backends because we are a standards-complaint build frontend. The uv init command only supports a subset of build backends, because those are the ones that have received a pull request adding the necessary template.

We don't have an opinionated default. We use hatchling right now, because we think it's a reasonable option. We're working on our own build backend, which will be used by default eventually. uv init --package or uv init --lib will set up the "default" build backend for you.

If you don't define a build backend, we won't install your project itself into the environment (but will still install its dependencies).

I believe these things are outlined in https://docs.astral.sh/uv/concepts/projects/init/#creating-projects (in addition to the build system document you referenced).

We could clarify the role of build frontends in the document you linked though.

[rsyring]

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),

I think digestibility of the sidebar could be made better with some styling changes. Currently, there isn't enough contrast between headings in the nav and the nav items. They are almost the same size, use the same font, have the same spacing, same color, etc. To me at least, that makes them run together and feels a bit overwhelming. Makes it harder to visually scan for what I'm looking for.

Consider mise's docs which have a similar volume of content in the sidebar nav but, at least to me, don't feel nearly as "crowded" or overwhelming:

[sanmai-NL]

The section Resolution - Required environments doesn't explain the syntax and certainly not the semantics of this environment marker language. From uv's docs on functionally similar features, I found a reference to PEP 508. That, however, is marked as deprecated when visited, and superseded by Dependency specifiers.

I propose that uv's documents this language in a single place, that references Dependency specifiers and just that.

[zanieb]

I think digestibility of the sidebar could be made better with some styling changes. Currently, there isn't enough contrast between headings in the nav and the nav items

Yeah I agree. This has been hard to get right and I've spent way too many hours futzing with it.

Unfortunately just copying over the colors from mise isn't great, imo

[zanieb]

Similarly, I think the bold looks bad

[cmsirbu]

How about this (fully realizing it steals the active link colour).

• Remove the padding override for inner menu items (leave it at the theme default?)
• Make categories more emphasized using md-nav__link--active

[rsyring]

@cmsirbu - I'm terrible at design. I usually try to find a template that has this done "right" by someone who knows aesthetics better than me. :) But, here are some thoughts:

• I think the latest attempt is an improvement worth publishing.
• What's the third level nav look like. I.e. when you are in "Integrations >" or "Projects >"?
• Try: making the 2nd level nav one size smaller font?
• I'm not a fan of the "purple" color in the light background version. There isn't enough contrast between that and white IMO. But that might be a different issue for a different time.

HTH. :)

[zanieb]

I guess I don't really see that as a clear step forward, especially since it clobbers the active link styling.

[zanieb]

It's also worth noting that ~half of the Mise nav is below the page fold. It's an explicit goal to minimize that here.

I think the proper fix for this is probably to add horizontal sections, which I've explored but will requires some serious reorganization and isn't a priority at the moment.

[cmsirbu]

@rsyring There's a limit to what one can do in a browser "inspect" window with average css skills, I know when to stop 🙂

I guess I don't really see that as a clear step forward, especially since it clobbers the active link styling.

It's more of a take from it what might be useful than "do this".

More to the point, I initially only wanted to post the padding option, which might be a good solution for adding visual separation if you don't want to increase the vertical spacing too much (to keep as much as possible on the screen).

Is it too much indentation? 🤷🏻 It's python we're talking about...

[rsyring]

It's also worth noting that ~half of the Mise nav is below the page fold. It's an explicit goal to minimize that here.

I'm not sure concern about what's above the fold is that helpful in technical documentation, especially navigation when it's intuitive, especially for technical users, to want to scan through something to easily get the "lay of the land." That's usually reserved for a different type of content and user interaction.

The audience who reads these docs is technical and giving them the ability to easily scan what the docs offer is a more important concern. I've never felt any hesitation when reviewing mise's docs b/c there is a lot of navigation. On the contrary, I've always found it helpful b/c it makes me aware of what's the there but easily allows me to move past it when I'm focused on a specific task.

To move this out of the realm of opinion, this might be a helpful reference: https://www.nngroup.com/articles/eyetracking-tasks-efficient-scanning/#toc-design-for-efficient-scanning-7

I think the proper fix for this is probably to add horizontal sections, which I've explored but will requires some serious reorganization and isn't a priority at the moment.

I'd encourage you to avoid horizontal navigation b/c it takes the scanning from a single dimension (vertical) to two dimensions (vertical + horizontal) and perhaps three dimensions if you have to click into a page in a section before you see it's horizontal navigation change. Makes getting the lay of the land much more difficult.

I think your current nav, two layers on left plus page TOC on the right once you are on a page is one of the best docs layout there is. Just need to visually de-clutter the left nav.

I guess I don't really see that as a clear step forward, especially since it clobbers the active link styling.

IMO, it is a clear step forward. Maybe not the last step, but the change in indentation and padding is a significant improvement.

I guess I'd have to see the full results but I didn't see anything that required clobbering the active link styling in the screenshots @cmsirbu provided. (missed a comment regarding)

Is it too much indentation? 🤷🏻 It's python we're talking about...

Nope. Just right IMO.

Don't forgot to preview the mobile/responsive versions.

Are all the font sizes the same? I think a slightly smaller font at each level will enhance visual distinction.

[rsyring]

Should we move the specifics of the nav changes to a different issue to avoid overwhelming this one?

[zanieb]

Let's chat in #11757

[Nugine]

(uv 0.6.5)
uv pip install does not update pyproject.toml or uv.lock. It seems surprising for new users.

[zanieb]

(uv 0.6.5) uv pip install does not update pyproject.toml or uv.lock. It seems surprising for new users.

pip does not do this, nor will uv pip. I think the solution here is #5200