Add an option to store virtual environments in a centralized location outside projects

[DanCardin]

I ideally dont .venv/ folders cluttering my project folders (not the least because they may not be safe to move, at least with venv)

In my personal (also rust) workflow tool (that i'd love to not have to maintain if uv could arrive at some of the same decisions 😆) there is a setting which when set to "central" puts all venvs in $XDG_DATA_HOME/<toolname>/..., and the path to the venv is determined by mirroring the path to the project. That is, ~/foo/bar/baz/pyproject.toml -> $XDG_DATA_HOME/uv/foo/bar/baz/.venv/.

By comparison to more traditional tools, poetry also (by default) will automatically create venvs in a central location. Although it puts all venvs in the same folder using a somewhat inscrutable hash to disambiguate projects of the same name.

---

This ^ feature sort of implies a few other mostly separate features in order to be useful:

• uv activate (because it becomes impractical to self-activate, except by copy-pasting the path that gets printed)
• which then implies some uv self init --shell zsh (or whatever), that gives you the shell integration to automatically activate through the CLI itself.
• uv venv --delete or -d

[zanieb]

Thanks for the issue!

This is the kind of thing we plan to tackle in the future, i.e. when we build an opinionated workflow for environment management. It's not in scope right this second, but we'll revisit it :)

[woutervh]

By comparison to more traditional tools, poetry also (by default) will automatically create venvs in a central location. Although it puts all venvs in the same folder using a somewhat inscrutable hash to disambiguate projects of the same name.

IMHO:
It's one of the really bad decisions of poetry.
As a python contractor usually supporting other python developers, I really dislike any situation where devs have no idea where their virtualenv of their project is. Your executables are the most important thing in your project, hiding them in arcane directories should never be a default.

Activating a venv is an antipattern because it introduces state in your shell.
I really hope it can be de-emphasized in the future.

[DanCardin]

Imo there are various positive sideeffects of the venv not being local, although I dont personally like their chosen algorithm for selecting it.

But ultimately, as long as the tool can know where the venv should be given the settings/invocation options, then there isn't generally a need to activate the venv, at least for uv itself to function. But it's the reality that many tools require VIRTUAL_ENV to be set to function properly, which either means activating the venv or routing all commands through a uv run (which might be nice interactively but isn't ideal for committed files imo).

[ResRipper]

I use Windows/Linux/Mac every day and synchronise my projects using OneDrive, having .venv in my project folder is such a nightmare, and that's why I started using pipenv. IMO venv should always be centralised as environments and packages are platform dependent, they are not part of the "content" of the project.

I'm using this plugin to manage and switch between different environments and don't have to know their location most of the time, but I do hope there is a standard for that.

[hauntsaninja]

Note uv currently appears to work if you make .venv file a symlink to your actual venv

If you don't have symlinks on your platform, this patch of uv may work for you by adding support for .venv files that point to the actual venv location: #1578 (comment)

When uv does go in the higher level workflow direction, I'd advocate leaving a .venv symlink or file pointing to the central location. This makes it easy for IDEs and other tools to figure out where the environment is. This .venv file / symlink idea was discussed around the time PEP 704 was a thing and had fairly positive support

[woutervh]

@hauntsaninja Thanks for the tip.

I was annoyed that uv does not support the most common normal use-case of virtualenv ootb:

> virtualenv foo
> cd foo
> bin/pip install <package1>

To make it work, the symlink indeed works

> uv venv foo
> cd foo
> ln -s .  .env
> uv pip install <package2>

It would be nice if "uv venv" would make the link by default.

And this would be a nice solution for managing venvs centrally outside the project-folder.

@ResRipper and for syncing via onedrive, you can point .venv to one of the os-specific .venv-files

.venv -> .venv-linux
.venv-linux  --> /some/linux/path
.venv-mac  --> /some/mac/path
.venv-windows  --> /some/windows/path

[matterhorn103]

Just to add my voice that this would be really really nice to have. Different tools seem to choose either one approach or the other, and it would be great if uv would do both as I like and use both in different situations:

For development situations where git is being used, having .venv there in the project's folder is convenient.

For other projects e.g. scientific ones that are in maybe shared or cloud or working folders, it's undesirable behaviour, and then working with conda is much smoother than with Python venvs. That's pretty much the only thing that keeps me using conda for some things (other than the different ecosystem, naturally).

My impression was that symlinks have poor portability, so like @DanCardin I'd prefer something like a simple -c switch to create the venv in an automatically determined central location, and simple automatic activation, e.g.:

~/example/foo >>> uv venv -c
Using Python 3.11.9 interpreter at: /usr/bin/python3
Creating virtualenv at: /home/jdoe/.local/share/uv/example/foo/.venv
Activate with: uv venv activate
~/example/foo >>> uv venv activate
Activating virtualenv at /home/jdoe/.local/share/uv/example/foo/.venv
(foo) ~/example/foo >>> deactivate
~/example/foo >>>

but with the addition that it would be cool to be able to also activate the venv by name from another location, with the search resolved intelligently and some ability to disambiguate; I could imagine that looking like:

~/some/folder >>> uv activate foo
Searching for virtualenvs at /home/jdoe/.local/share/uv/**/foo/.venv
Activating virtualenv at: /home/jdoe/.local/share/uv/example/foo/.venv
(foo) ~/some/folder >>> uv activate bar
Searching for virtualenvs at /home/jdoe/.local/share/uv/**/bar/.venv
error: virtualenv name is ambiguous! The following matches were found:
  1) /home/jdoe/.local/share/uv/Documents/bar/.venv
  2) /home/jdoe/.local/share/uv/project1/bar/.venv
disambiguate venvs with the same name using parents e.g. to activate 1) use:
  uv venv activate Documents/bar
(foo) ~/some/folder >>> uv activate project1/bar
Searching for virtualenvs at /home/jdoe/.local/share/uv/**/project1/bar/.venv
Activating virtualenv at: /home/jdoe/.local/share/uv/project1/bar/.venv
(bar) ~/some/folder >>>

[matterhorn103]

So in addition to the "not wanting the venv to be stored in a folder that is backed up to the cloud" use case, I found another use case today:

• Creating compiled binaries of Qt apps written with PySide using pyside6-deploy (a nuitka wrapper) isn't possible if a venv folder is present in the application folder

(In my view this is a short-sighted approach on the tool's part, but it's just another example of why it might be necessary to keep a venv elsewhere.)

[callegar]

When uv does go in the higher level workflow direction, I'd advocate leaving a .venv symlink or file pointing to the central location.

and

It would be nice if "uv venv" would make the link by default.
And this would be a nice solution for managing venvs centrally outside the project-folder.

Even this makes things more complex than needed if you sync to the cloud across multiple systems, because the link might need to be to different places on different machines.

If only for compatibility and ease of migration from one tool to another, I would offer the possibility to do what pdm does. That tool offers either the option to have a local .venv or the option to have venvs stored all together in a centralized place.

Note that having the venvs all stored in a single place also makes it easier to apply deduplication tools on suitable filesystems.

[PhilipVinc]

@zanieb is this a feature you're considering for the short term, or it's not high priority?

[luqasz]

I am using mac TimeMachine in which I've excluded $HOME/Library/Caches folder. Virtual envs can be large in size. No need to backup venvs since they can be reproduced.

[edmorley]

I am using mac TimeMachine in which I've excluded $HOME/Library/Caches folder. Virtual envs can be large in size. No need to backup venvs since they can be reproduced.

See also #8796 for an alternative way the Time Machine issue could be resolved. (uv already creates CACHEDIR.TAG, however, Time Machine doesn't honour that and instead needs different extended attributes to be set).

[luqasz]

I am using mac TimeMachine in which I've excluded $HOME/Library/Caches folder. Virtual envs can be large in size. No need to backup venvs since they can be reproduced.

See also #8796 for an alternative way the Time Machine issue could be resolved. (uv already creates CACHEDIR.TAG, however, Time Machine doesn't honour that and instead needs different extended attributes to be set).

Thx for that. I'll add hook in fish shell to exclude .venv dirs as a temporary fix.
BTW. You can 'borrow' solution from cargo ;-)

[ParticleMon]

In my workflow, multiple projects may use one venv, and only project code is synced with a repo, not venvs.

Having come from conda/mamba, I would be content with uv supporting centralized projects, to:

• Create projects centrally
• List venvs from anywhere
• Activate and deactivate from anywhere (ideally deprecated but it's unclear how this would affect IDEs)

So, I wrote three scripts (batch files, one that runs a bash script—thanks to the inclusion of recent GNU coreutils in git). High-level, the scripts:

• Create - Takes arguments specifying the venv name, Python version number, and optional dependencies .txt and a sync flag.
• Activate - With no argument, lists venvs, the Python version, and if present, the project description; or, activates the specified venv.
• Deactivate - Takes no argument.

The bash script lists the venvs, parsing dirs and files.
The de/activate scripts eliminate having to cd.
Additional batch files are merely aliases ("act" and "deact," convenient but otherwise unnecessary).

uv_utils.zip
For the scripts, set these environment vars:
uv=C:\path\to\uv-dirs-parent
uv_gnu=/mnt/c/path/to/uv-dirs-parent

[eabase]

@ParticleMon

So, I wrote three scripts

Well, where are they?

[ParticleMon]

@eabase Attached.

[mustafa0x]

Using mise, this should work.

UV_PROJECT_ENVIRONMENT = "~/.cache/.envs/{{cwd | basename}}"

[eabase]

Using mise, this should work.

Whats "mise"?

[monk-time]

Could the discussion about alternative workarounds that's not connected with uv implementing the feature be moved someplace else? There's way too much noise on this ticket.

[xmo-odoo]

* `uv activate` (because it becomes impractical to self-activate, except by copy-pasting the path that gets printed)

I've not seen any mention of it so I wanted to say that pyenv has a pretty neat (I think) feature for that: the "global" virtualenvs have the same status as "pure" python versions, so if .python-version contains a global venv name that venv will be auto-activated.

[krstp]

Yeah, I tend to fall back to multiple venv with pyenv-venv, then whatever is needed I go with uv. This provides a stable and consistent dev solution and envs. For now that is the way.

[lukeemhigh]

I stumbled upon this discussion while looking for a way to emulate my pyenv+poetry workflow.

I generally manage my virtual environments with pyenv-virtualenv because I like the simplicity of setting an environment variable (PYENV_ROOT in case of pyenv, but could be equally good to use uv's config file) and have all my python versions and virtual environments centrally managed, and not scattered around my workspace.

Ultimately, I think an environment variable/config file approach is better for this feature, to me having to specify a flag to uv venv at every environment creation is an undesirable step that a declarative approach could spare us.

[krstp]

Imho, either config file or attribute file, both options would be good to have.

Here is also an interesting turn of things... in the past days I had to work with Win11 box... as unusable as Windows-box is, it made me install virtual Ubuntu shell via WSL...

Long story short, when installing uv under virtual shell, that by default runs bash changed to zsh, some strange reference base python thing happens that instead of seeing *nix python versions, it sees the underlying Win11 pythons that clearly make it unusable or with some gimmicks will allow Win11 layer pythons usage which is super inefficient.

The core issue was, whenever I tried to instantiate uv venv, uv would not find the right python references, uv simply could not see and recognize the *nix layer pythons!

What did came with a rescue was pyenv, that carries correct local zsh references. So running pyenv and then uv for pip sync etc works just fine.

This also shows the inner-works of core uv for python env instantiation.. such as it runs on diff python references than follow up commands, which makes sense. However, relying only on uv under WSL-ubuntu for venv was not finalizing with success, by ingesting windows python references ¯_(ツ)_/¯ or rather unable to even correctly ingest those producing an error, which also makes sense.

Atm, I am not even opening the issue. (#12185)
This just shows uv runs better natively. And yes I did reinstall uv under WSL, it would still find win11 references. I just wanted to give context why combination of pyenv with uv might be better in such scenario, where pyenv-venv yields some more env stability. Also this is not the first time pyenv-venv comes to the rescue, I am mostly mac and *nix user, and whatever hurdles I was dealing with in those systems in local development, the virtual env layer with pyenv-venv came each time to the rescue. o7

[zanieb]

Is this the same as

• No interpreter found in search path on nixOS #10711
• Regression: uv fails to detect nixpkgs provided python as a valid system-managed interpreter when it's installed with libraries #11529
• Venvs from uv and from native python works a little different on nix #4450

[krstp]

Indeed, somewhat related.

I cannot provide now detailed steps I have taken as I was rushing through setup, but through multiple resourcing of the env, now I am able to activate uv created env. Either way, it seems to be more of an issue of virtualized system layer python reference than uv itself.

Thanks for the follow up.

[ssbarnea]

Another usecase: Some of my colleagues work mainly on network drives, however Python is really slow loading a huge env from a network drive. Poetry is currently a good fit, as the default location of the venv is somewhere on the local SSD which speeds up loading significantly.

Very similar use case: use of VMs to perform cross-platform compatibility. I use Parallels on MacOS and have VMs with Ubuntu, Fedora and Windows where I run tests on the same code (code folder is mounted on these.

We use tox for testing which creates by default .tox temp directory inside the project, but because for can also allow users to override the default via env variables, TOX_DIR=.tox/$(hostname), we found a way to isolate these between machines. Feel free to use this as a workaround as tox-uv also adds support for uv.

Still, if you just want to use uv outside tox on different platforms, we need this bug fixed.

[jnakanojp]

My workaround is to create a set_env.sh file and source it before using uv.
The contents of set_env.sh are as follows:

#!/bin/sh
export UV_PROJECT_ENVIRONMENT=~/.local/uv/my_special_secret_project

Before using uv, I run the following command to load the environment variable:

. set_env.sh

Since this step is manual, I sometimes forget to run it, and as a result, .venv may be created by mistake.
It might be possible to automate this process by using a tool like direnv.