Add a "storage" reference document by zsol · Pull Request #15954 · astral-sh/uv

zsol · 2025-09-19T20:22:11Z

This is based on, and supersedes @zanieb's #13976

docs/reference/storage.md

zsol · 2025-11-02T04:03:09Z

Thanks for all the feedback. I've rewritten the first section (directory strategies) based on it, including the excellent table @konstin mentioned, extending it a bit. I think the page is now more concise, less repetitive.

After some digging, I now think that .uv in the current directory is technically a fallback in the code, I think that branch is unreachable because uv_dirs::user_state_dir() always returns an Ok value, so I removed that bit from the docs. We should get rid of it from the code, too, IMO.

konstin · 2025-11-04T16:37:27Z

After some digging, I now think that .uv in the current directory is technically a fallback in the code, I think that branch is unreachable because uv_dirs::user_state_dir() always returns an Ok value, so I removed that bit from the docs. We should get rid of it from the code, too, IMO.

The code can fail if there's a HomeDirError cause the home dir function is fallible. From my experience there's always some minimal Docker or some Windows entreprise configuration where it fails, so a .uv fallback is convenient.

docs/reference/storage.md

konstin · 2025-11-04T19:10:24Z

docs/reference/storage.md

+| Purpose                    | Unix Default                                                               | Windows Default                                         |
+| -------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------- |
+| Temporary files and caches | `$XDG_CACHE_HOME/uv` or `~/.cache/uv` as a fallback                        | `%LOCALAPPDATA%\uv\cache`                               |
+| Persistent data            | `$XDG_DATA_HOME/uv` or `~/.local/share/uv` as a fallback                   | `%APPDATA%\uv\data` if exists, otherwise `%APPDATA%\uv` |


On a fresh install, it uses %APPDATA%\uv to e.g. install Pythons, we should document that as default location, the %APPDATA%\uv\data exists only not to break legacy paths.

Agreed. Do you think it's important to emphasize this nuance here? I think what the PR has currently is correct.

I'd document where a user can expect their data to go, and which levers they have to change this. So I'd put %APPDATA%\uvcentrally: It's the location to find uv data, and changing APPDATA can change the location of uv data. %APPDATA%\uv\data should be more akin to a footnote, it something that may be used on a legacy setup, but never when setting something new up, or when changing the location manually. Currently, it reads to me as if %APPDATA%\uv\data is the main one, and %APPDATA%\uv is a fallback.

OK, changed it. PTAL

I omitted the legacy location entirely, that's really old functionality.

docs/reference/storage.md

zsol · 2025-11-05T13:43:28Z

Thanks! I addressed all of your feedback except for the one I replied to

konstin

Thanks!

samypr100 · 2025-11-05T17:22:57Z

Should we pull in the changes from #16590 here?

docs/reference/installer.md

zsol · 2025-11-17T11:04:56Z

docs/reference/storage.md

+    - `$TMPDIR`
+    - `/tmp`
+
+=== "Windows"
+
+    - `%TMP`
+    - `%TEMP`
+    - `%USERPROFILE`


IMO these should be numbered to make the order of preference clear.

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [astral-sh/uv](https://github.com/astral-sh/uv) | patch | `0.9.9` -> `0.9.10` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>astral-sh/uv (astral-sh/uv)</summary> ### [`v0.9.10`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0910) [Compare Source](astral-sh/uv@0.9.9...0.9.10) Released on 2025-11-17. ##### Enhancements - Add support for `SSL_CERT_DIR` ([#16473](astral-sh/uv#16473)) - Enforce UTF‑8-encoded license files during `uv build` ([#16699](astral-sh/uv#16699)) - Error when a `project.license-files` glob matches nothing ([#16697](astral-sh/uv#16697)) - `pip install --target` (and `sync`) install Python if necessary ([#16694](astral-sh/uv#16694)) - Account for `python_downloads_json_url` in pre-release Python version warnings ([#16737](astral-sh/uv#16737)) - Support HTTP/HTTPS URLs in `uv python --python-downloads-json-url` ([#16542](astral-sh/uv#16542)) ##### Preview features - Add support for `--upgrade` in `uv python install` ([#16676](astral-sh/uv#16676)) - Fix handling of `python install --default` for pre-release Python versions ([#16706](astral-sh/uv#16706)) - Add `uv workspace list` to list workspace members ([#16691](astral-sh/uv#16691)) ##### Bug fixes - Don't check file URLs for ambiguously parsed credentials ([#16759](astral-sh/uv#16759)) ##### Documentation - Add a "storage" reference document ([#15954](astral-sh/uv#15954)) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

zsol requested a review from zanieb September 19, 2025 20:22

zsol force-pushed the zsol/storage-docs branch from fbe2564 to 8457437 Compare September 19, 2025 20:26

zsol marked this pull request as ready for review September 19, 2025 20:28

zsol added the documentation Improvements or additions to documentation label Sep 19, 2025

zsol marked this pull request as draft September 19, 2025 20:29

zsol force-pushed the zsol/storage-docs branch from 8457437 to 2a1effb Compare September 19, 2025 20:33

zsol marked this pull request as ready for review September 19, 2025 20:34

zanieb self-assigned this Sep 20, 2025

konstin mentioned this pull request Oct 9, 2025

How to find the virtual environment path for a project in uv and other ENV in general? #16202

Open

geofft reviewed Oct 13, 2025

View reviewed changes

konstin reviewed Oct 14, 2025

View reviewed changes

docs/reference/storage.md Outdated Show resolved Hide resolved

zanieb and others added 3 commits November 1, 2025 22:50

Add a "storage" reference document

e895de4

expand on the storage documentation and add links back to it

a4ded8d

reformat

ab18613

zsol force-pushed the zsol/storage-docs branch 2 times, most recently from 1df95e2 to 74ab526 Compare November 2, 2025 03:55

Rewrite the Directory Strategies section

59fac59

zsol force-pushed the zsol/storage-docs branch from 74ab526 to 59fac59 Compare November 2, 2025 03:57

konstin reviewed Nov 4, 2025

View reviewed changes

zsol had a problem deploying to uv-test-registries November 5, 2025 13:44 — with GitHub Actions Error

zsol had a problem deploying to uv-test-publish November 5, 2025 13:44 — with GitHub Actions Error

zsol force-pushed the zsol/storage-docs branch from 662f8af to 8e54cb2 Compare November 5, 2025 13:44

review feedback

000243f

zsol force-pushed the zsol/storage-docs branch from 8e54cb2 to 000243f Compare November 5, 2025 14:42

konstin approved these changes Nov 5, 2025

View reviewed changes

zanieb reviewed Nov 14, 2025

View reviewed changes

docs/reference/installer.md Outdated Show resolved Hide resolved

zanieb temporarily deployed to uv-test-registries November 14, 2025 18:48 — with GitHub Actions Inactive

zanieb had a problem deploying to uv-test-publish November 14, 2025 18:48 — with GitHub Actions Error

Zanie does some restructuring and hopes it isn't offensive

132a0ba

zanieb force-pushed the zsol/storage-docs branch from 188587a to 132a0ba Compare November 14, 2025 18:56

zsol commented Nov 17, 2025

View reviewed changes

zsol added 2 commits November 17, 2025 11:09

Bullets -> numbers

746821c

Fix typos in Windows directories and add links to constants

5a75ebe

zsol temporarily deployed to uv-test-registries November 17, 2025 11:23 — with GitHub Actions Inactive

zsol merged commit 6f525f9 into main Nov 17, 2025
99 of 100 checks passed

zsol deleted the zsol/storage-docs branch November 17, 2025 14:38

BrewTestBot mentioned this pull request Nov 17, 2025

uv 0.9.10 Homebrew/homebrew-core#254745

Merged

samypr100 mentioned this pull request Nov 18, 2025

Clarify user-level and system-level configuration file locations #16590

Open

Comments

Conversation

zsol commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zsol commented Nov 2, 2025

Uh oh!

konstin commented Nov 4, 2025

Uh oh!

Uh oh!

Uh oh!

konstin Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

zsol Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

konstin Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

zsol Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

zanieb Nov 14, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zsol commented Nov 5, 2025

Uh oh!

konstin left a comment

Choose a reason for hiding this comment

Uh oh!

samypr100 commented Nov 5, 2025

Uh oh!

Uh oh!

zsol Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

zsol commented Sep 19, 2025 •

edited

Loading