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.

[charliermarsh]

@willmurphyscode -- It's not documented anywhere, only implicitly in code. We don't have any planned changes but I'm sure it will change over time (it's also versioned). Separately, if PEP 751 is approved (which I've been very involved in), we'll likely migrate to whatever the approved format is, if it works for uv.

[jonasdeyson]

The section Non-editable installs led me to a mistake.

It mentions the following:

By default, uv installs projects and workspace members in editable mode...

And then:

In the context of a multi-stage Docker image, --no-editable can be used to include the project in the synced virtual environment from one stage, then copy the virtual environment alone (and not the source code) into the final image.

The problem is that, if I understand correctly, this is only true if the project was created as a library (uv init --lib).
An app project doesn't seem to be installed as editable by default in the venv (contrary to what the previous quote says).
Since the example Dockerfile shown there is clearly for an application, it got me confused for a while.

I suggest to make it more clear that only library projects are installed in the environment, regardless of the flag --no-editable.

[debnath-d]

#5605 (comment) :

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

@zanieb I would also like to know this.

[zanieb]

@debnath-d The .python-version file can be read by other tools like GitHub Actions to determine which version to install. The version file pins to a single version whereas the pyproject.toml field is intended to define a range of versions supported by your application or library (per the Python standards).

[AndreuCodina]

@debnath-d The .python-version file can be read by other tools like GitHub Actions to determine which version to install. The version file pins to a single version whereas the pyproject.toml field is intended to define a range of versions supported by your application or library (per the Python standards).

For me, if you use uv init --lib, it makes sense to have requires-python and .python-version. But if you use uv init --app, I think it isn't useful (requires-python is not required and you already have .python-version).

It's the same feeling I have when I use uv init --app and the description field is added to my application with a default value I'll never use.

If requires-python could be used by child packages it'd be okay, but when you run uv init --lib inside a project, another pyproject.toml with a requires-python is created. For example, in my .NET repositories, I define the .NET version of all packages in a root file (similar to pyproject.toml).

BTW, pyproject.toml can also be used with GitHub Actions.

[bongomachine]

It would be great if you:

1. Add some example(s) of a larger and more complex project/workspace.
2. If you add an example of how to use Hatchling build hooks.

[mdegis]

I think it would be great if there a page about how to migrate from poetry.

[Rogdham]

In the documentation about configuration, I find it confusing that many settings can be set in both tool.uv and tool.uv.pip (and they seem to have the same description).

What is the difference? Is there inheritance? Should I set them in both places?

List of the 23 impacted settings at the time of writing

• allow-insecure-host
• compile-bytecode
• config-settings
• dependency-metadata
• exclude-newer
• extra-index-url
• find-links
• index-strategy
• index-url
• keyring-provider
• link-mode
• no-binary
• no-build
• no-build-isolation
• no-build-isolation-package
• no-index
• no-sources
• prerelease
• reinstall
• reinstall-package
• resolution
• upgrade
• upgrade-package

[zanieb]

@mdegis you can track that at #5200

@Rogdham please see https://docs.astral.sh/uv/configuration/files/#configuring-the-pip-interface

[yaleman]

It'd be good to mention in the working on projects section of the guide, perhaps under the "running commands" part, that you need to include a build system or the library won't be available. This is a pretty confusing footgun that lost me most of a day while trying to work out why pytest wouldn't find my library.

The only mention of this I can find is an easy-to-misread sentence under the build systems part of Concepts -> Projects.

[zanieb]

👍 sorry to hear that @yaleman — that change was made after we wrote most of the documentation and I've been meaning to rewrite the project documentation to account for that.

[Rogdham]

@Rogdham please see https://docs.astral.sh/uv/configuration/files/#configuring-the-pip-interface

Thank you for this, much helpful! Maybe just add a link to it in https://docs.astral.sh/uv/configuration/files/#configuring-the-pip-interface?

A small note in each field of pip config saying that it inherits would be ideal, but I understand that this is quite some work for little benefit.

[powercoconola]

Thanks for your work on the project.
It would greatly help to write a way to change these environment variables. I am a bit lost how to change UV_TOOL_DIR to something different. In other words, change the result of uv tool dir
https://docs.astral.sh/uv/configuration/environment/

Here in the documentation it says to change the environment variable but nowhere on how to do that
https://docs.astral.sh/uv/concepts/tools/#tools-directory