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 https://github.com/astral-sh/uv/issues/6153

[zanieb]

Maybe we can improve the uvx to uv tool transition in the guide https://github.com/astral-sh/uv/issues/6334#issuecomment-2302439899

[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 https://github.com/astral-sh/uv/issues/6334#issuecomment-2302439899

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 https://github.com/astral-sh/uv/issues/6425

[zanieb]

@gusutabopb let me know if #6468 is sufficient!

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

• https://github.com/astral-sh/uv/pull/6474 and
• https://github.com/astral-sh/uv/pull/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.