Documentation feedback
Opened this issue · 114 comments
This is a tracking issue for feedback on the new documentation at https://docs.astral.sh/uv/
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.
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.
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!
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
Maybe we can improve the uvx to uv tool transition in the guide #6334 (comment)
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 updateMinor 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
uvxoruv 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?
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 😅.
(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
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.
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
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?
I'm not sure why there's a python-version file if this information is also in the pyproject.toml.
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.
@shunichironomura thanks! I think we need to create a separate "Scripts" concept page because that's way too advanced for the "guide" documentation.
Would be nice to have information on whether virtual workspaces (no project and build-system sections in pyproject.toml?) like Cargo are supported.
You might be looking for this: https://docs.astral.sh/uv/concepts/projects/#applications
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.
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.
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)
@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.
@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.
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.
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.
@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).
@debnath-d The
.python-versionfile can be read by other tools like GitHub Actions to determine which version to install. The version file pins to a single version whereas thepyproject.tomlfield 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.
It would be great if you:
- Add some example(s) of a larger and more complex project/workspace.
- If you add an example of how to use Hatchling build hooks.
I think it would be great if there a page about how to migrate from poetry.
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
@mdegis you can track that at #5200
@Rogdham please see https://docs.astral.sh/uv/configuration/files/#configuring-the-pip-interface
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.
👍 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 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.
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
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 :)
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: trueWill this cache both Python and dependencies?
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?
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.
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.
The "when (not) to use workspaces" section conflates
- Actual use cases for workspaces:
uv/docs/concepts/workspaces.md
Lines 152 to 165 in 94fc35e
- Use cases not well suited for workspaces
uv/docs/concepts/workspaces.md
Lines 167 to 168 in 94fc35e
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?)
The dependencies are primarily specified in pyproject.toml, then
uv syncupdates 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.
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.
@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)
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?
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.
If anybody is looking to get started with migrating from poetry to uv, I documented the approach I took here: #5200 (comment).
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 --frozenis what you're looking for @bjornasm?
Thank you, that seems what I am after!
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?
Hi guys, I just wanted to report that the Discord invitation link provided here in the documentation is expired.
As a Chinese language user, I would like to inquire whether the UV community's documentation requires internationalization translation, and I am willing to contribute a Pull Request for the Chinese translation of the UV documentation.
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?
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?
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.
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.
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
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.
https://docs.astral.sh/uv/guides/scripts/ doesn't explain where uv creates environments and how to clean up them after.
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
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!
@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.
@eliasdabbas cool thank you! cc @dhruvmanila for Ruff's documentation.
@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.
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_URLis 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!
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?
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.
@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.
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!
@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/
@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.
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
@carrollpaul I tested that just now and cannot reproduce. Please open an issue with a reproduction.
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
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.
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.
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.txtbefore making changes. I know I can do the same withuv pip freeze, but I was curious if there is a better way to handle this using uv tools.
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.
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:
- I had skipped over some of the concept docs and used the CLI command reference docs as my starting point.
- 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).
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 ?
That’s awesome feedback, thanks @edmorley.
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
uvor 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
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.
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:
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.
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
Similarly, I think the bold looks bad
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
@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. :)
I guess I don't really see that as a clear step forward, especially since it clobbers the active link styling.
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.
@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...
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.
Should we move the specifics of the nav changes to a different issue to avoid overwhelming this one?
uv documentation uses "Material for mkdocs". It is a small team (until recently one single person).
They are busy revamping it for speed and better search. But they have always the time to answer any question related to style or changes.
(uv 0.6.5)
uv pip install does not update pyproject.toml or uv.lock. It seems surprising for new users.
(uv 0.6.5)
uv pip installdoes not updatepyproject.tomloruv.lock. It seems surprising for new users.
pip does not do this, nor will uv pip. I think the solution here is #5200
I am not sure, if here is the right place, but It seems to miss in the documentation the recommended way of installation uv system wide, for an admin managing a multi-user linux it could be helpful.
@vitrinite yeah the multi-user setup is kind of complicated and depends a lot on the use-case so we haven't captured it in the documentation. There are various issues in the tracker where people are talking about their setups though.
In the docs for the official GitHub action, the advice for manually managing the uv cache is to set UV_CACHE_DIR in the global environment for the job. However, the setup-uv action overwrites the value of UV_CACHE_DIR; this behaviour is documented in the action's README. It seems the proper thing to do is to use the value of UV_CACHE_DIR set by the action:
jobs:
install_job:
steps:
# This action sets the UV_CACHE_DIR env var, even if it was already set
- name: Setup uv
uses: astral-sh/setup-uv@v5
- name: Restore uv cache
uses: actions/cache@v4
with:
path: ${{ env.UV_CACHE_DIR }} # changed
key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
restore-keys: |
uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
uv-${{ runner.os }}
# ... install packages, run tests, etc ...
- name: Minimize uv cache
run: uv cache prune --ciAlternatively, --cache-dir $UV_CACHE_DIR could be explicitly passed to all uv invocations in the workflow, or possibly cache-local-path could be set in the options for setup-uv.
How do you guys deal with minor errors in documentation (or code), such as typos, in such a massive repository? 'a' instead of 'an' is such an insignificant issue, should it be somewhere reported, proposed inprovement with a PR, or ignored completely?
@dasAtRagedy feel free to just post a pull request! We're always happy to merge small fixes.