Skip to content

Initial design doc for centralized venvs - #14628

Open
rsyring wants to merge 2 commits into
astral-sh:mainfrom
rsyring:1495-centralized-venvs
Open

rsyring wants to merge 2 commits into
astral-sh:mainfrom
rsyring:1495-centralized-venvs

Conversation

@rsyring

@rsyring rsyring commented Jul 15, 2025

Copy link
Copy Markdown

@PhilipVinc

Copy link
Copy Markdown
Contributor

+1 on my side.
I would change the default directory for the venv cache to be UV_CACHE_DIR/venvs-v0/ because ÙV_CACHE_DIR already falls back to XDG_CACHE_DIR?

Setting the venv cache in the same filesystem of the UV cache is what you want to do anyway to get decent performance.

I will also mention that the calculation of the path within the cache is a good idea in my opinion, and that's what I've been using for the past year or so.

@rsyring

rsyring commented Jul 15, 2025 •

Copy link
Copy Markdown
Author

I would change the default directory for the venv cache to be UV_CACHE_DIR/venvs-v0/ because ÙV_CACHE_DIR already falls back to XDG_CACHE_DIR?

Will do. The XDG_CACHE_DIR in the spec was really a placeholder b/c I'm not sure what the uv internals look like. I'm sure there is some kind of "global" or context object that takes all env vars and settings into account and provides a cache_dir variable that everything else then uses. I really intend to reference that. I'll update the spec to clarify.

I will also mention that the calculation of the path within the cache is a good idea in my opinion, and that's what I've been using for the past year or so.

I understand this to mean that you affirm the "Human‑readable slug + short hash" approach. Please correct my understanding if needed.

Thanks for the feedback.

Comment thread design/1495-centralized-venvs.md Resolved
@rsyring

rsyring commented Jul 16, 2025

Copy link
Copy Markdown
Author

I figured I'd give this another few days for comments and then address them all and update the proposal.

Where there are different preferences expressed, my intention is to make a reasonable decision with the MVP goal in mind, aware that it may potentially not satisfy everyone, giving preference to input given by current uv contributors.

If there is a "designated" decision maker for something like this in the uv org, they are welcome to step into the decision making role at any point and I'll take a step back.

Thanks everyone.

@eabase

eabase commented Jul 16, 2025

Copy link
Copy Markdown

This looks over-engineered and not like a MVP.
Why do you need to specify different python versions within the same project (or venv)?

See my comments here.

@rsyring

rsyring commented Jul 30, 2025

Copy link
Copy Markdown
Author

I've updated the proposal based on the feedback/discussion here. Thoughts?

@rsyring

rsyring commented Aug 11, 2025

Copy link
Copy Markdown
Author

Any thoughts on my updated proposal?

Is there a formal approval process? If not, at what point it it safe to start the implementation?

@eabase

eabase commented Aug 29, 2025

Copy link
Copy Markdown

@rsyring
Hi Randy,

Regarding:

Sorry, but I'm not happy with your proposal, as it lacks clarity and I fail to see how it would help the current implementation. I'm also worried about the cache idea. For me anything that is in a cache can be discarded at any time without serious consequences, as it can be easily rebuilt. However, this is not the case for the venv "repo" directories we are talking about and discussing in #1495. Very often we have certain dependencies for HW related projects (like Nvidia, Nordic Semi, etc) that requires different package versions, and where nobody should be able to do a generic "clear cache" to wipe out all your venv's. I'm sure (or at least I hope) that I have the wrong understanding of this.

Also, the "Human‑readable slug + short hash" is just not a productivity improvement. I don't want to have to look up and carefully type in any kind of hash in order to activate, copy, move or duplicate any venv. I'm certainly missing to see the use case for this?

So can you please update us on what exactly is the new proposal and what functionality it provides that simplifies life to the user, via UX?

@rsyring

rsyring commented Aug 29, 2025

Copy link
Copy Markdown
Author

@eabase I can appreciate that you don't prefer this proposal. However, I did process your previous comments on this issue and I believe they are all addressed in the "Out of Scope / Rejections" section.

I don't plan on doing any additional work on this proposal until someone from Astral gives some definitive feedback. While I think this PR/idea had some momentum originally, the momentum/interest has seemed to die. And I don't want to put more time into it unless there is the possibility of an implementation somewhere in the near-term. If we get that feedback, and it aligns with your concerns/preferences, I'm happy to take another stab at revising the proposal.

Thanks.

@eabase

eabase commented Aug 30, 2025

Copy link
Copy Markdown

@rsyring

they are all addressed in the "Out of Scope / Rejections" section

That's exactly my point of my last comment. I don't understand what you mean with "Out of Scope / Rejections". Are you rejecting your own proposal, or the comments/proposals from everyone else?

@rsyring

rsyring commented Aug 30, 2025

Copy link
Copy Markdown
Author

@eabase

I don't understand what you mean with "Out of Scope / Rejections". Are you rejecting your own proposal, or the comments/proposals from everyone else?

In the design doc, the final section of the document is "Out of Scope / Rejections." That section lists items that I considered but decided were out of scope or am rejecting for this proposal. For example, I don't think we should be concerned with the accidental deletion of virtualenvs in the cache and I give my reasoning in that section.

Hope that helps.

Comment thread design/1495-centralized-venvs.md Resolved
Comment thread design/1495-centralized-venvs.md Resolved
- This is not limited to the venv-in-cache feature
- E.g.: `print($uv_venv_dir)`
1. Cache cleanup
- `uv cache clean` removes all venvs

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

uv cache clean already exists and has functionality (remove all cache).

I think there should be a dedicated command for this - which cleans all environments - but leaves the actual cache in place (under the assumption that centralized venvs are combined with local venvs).

@rsyring rsyring Aug 31, 2025 •

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there should be a dedicated command for this

I agree that would be preferable.

However, in this iteration, I specifically didn't address this because I wanted to avoid specifications that would lead to additional debate or work and, perhaps, delay the initial implementation.

IMO, there are two functions that uv could provide:

  • clean: completely delete all centralized venvs
  • prune: delete any centralized venv where the venv's project directory (which is tracked in $venv_dir/uv-project-path.txt) no longer exists

Where in the CLI those functions live is what I thought could lead to delay. Options I've considered:

  • uv venv --cache-clean
  • uv venv --cache-prune
  • uv cache clean --venvs/--no-venvs
  • uv cache prune --venvs/--no-venvs
  • uv cache venvs clean
  • uv cache venvs prune

With my preference being the last two.

@xmatthias xmatthias Sep 1, 2025 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure i agree on your "delay implementation" stance - the current proposal to overload an existing command (without optionality, from the proposal) can have the adverse effect and (at least in my opinion / view) can/could lead to more discussions.

I think these options could be listed as "alternatives" at least - giving astral folks the option to pick the one they prefer"?
Currently it's "we'll use uv cache clean." - if that doesn't fit their plans / UX view - there's no considered alternatives listed (outside of the above comment).

zanieb added a commit that referenced this pull request Jul 15, 2026
Centralized environment keys use lexical workspace paths, so reaching
one project through a directory symlink creates a second environment and
reinstalls its dependencies. Canonicalize workspace identity before
selecting the centralized environment, preserving the single-environment
expectation from the centralized-environment design in
[uv#14628](#14628) and
[uv#18214](#18214).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants