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.

[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

[powercoconola]

https://docs.astral.sh/uv/guides/tools/
In this page, the documentation reads
"The uvx command invokes a tool without installing it."
Then a few lines down it says:
"When uvx ruff is invoked, uv installs the ruff package which provides the ruff command."
So does uvx install the package or not? Thank you for your work on this project :)

[merlinz01]

https://docs.astral.sh/uv/guides/integration/github/

Do I have to specify enable-cache in a separate caching workflow step, or do I simply add it to the original setup-uv step? If it is a separate step, where does it go in relation to the other steps?

- name: Enable caching
  uses: astral-sh/setup-uv@v3
  with:
    enable-cache: true

Will this cache both Python and dependencies?

[bjornasm]

How do I actually work with the uv.lock file?

I have pushed it to the repo, and are now pulling it on another computer. If I do uv.sync then the uv.lock file is emptied to reflect (the empty) pyproj.toml. But I want the opposite, that all the packages in uv.lock are installed to pyproj.toml?

[merlinz01]

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.

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