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?

[callegar]

Off topic

It is a matter of what you are used to and what you are doing. Yes, in many cases not having the shell hold the a state can be advantageous. Yet, depending on what you do typing uv run every time might end up more verbose than typing uv venv --activate once (should anything like this get supported or . .venv/bin/activate otherwise). Furthermore, there are really cases when you want to use uv, not to develop a project, but just to have a well defined virtual environment to play in (think working on notebooks that need a specific environment). In the latter case, you may really prefer having the shell holding the state to assure that you can cd to different places maintaining the state.

[mil-ad]

I tried setting UV_PROJECT_ENVIRONMENT to something like export UV_PROJECT_ENVIRONMENT=/scratch/$USER/venvs/${PWD#$HOME}" for all users.

This mostly works but I'm one issue I'm having is that uv venv ignores UV_PROJECT_ENVIRONMENT #10807

[Badg]

As with others, I'm in a situation where I'm syncing source code via dropbox in addition to using git. I do this because I very frequently switch between a windows desktop computer and my (osX) laptop for development, and don't want to bother with git stash, WIP commits, etc. I just want to save my files, shut down my computer, and continue working on the go.

I've only skimmed the above discussion, so apologies if I'm missing someone commenting this already. But: at first glance, the idea of "just add a file to the project with a path to the .venv" seems like it would work (analagous to the .git file -- not folder -- which, side note for anyone else in this situation, allows you to relocate your git directory outside of your cloud sync provider).

The problem I've run into is that this forces all of your devices to use the same location for your environments (or your git directories), because -- even though it's ignored by git -- the .git file gets synced by your cloud provider. So in my case, that means I'd need to have a parent directory to store all of my .git repos that's the same on both windows and osx. To complicate matters further, my system language is usually set to german, and localization of system paths (like the users directory) is handled differently on both platforms. This means that a subfolder of the drive root is the only reliable place I can store my git directories. In short, it's a huge pain in the ass, and it really only works because I'm the only person using it. If you were in a shared cloud sync account, that would break down really quickly.

The way other python tools handle this (at least as far as I've seen) is that, when you enable a global/user setting to store the managed virtual envs in a centralized location (for example, in poetry, by setting the virtualenvs.in-project option to false), they make some kind of combination of the project's folder name and a hash of the path to the project (to avoid collisions based on the folder name, or to allow multiple clones of the same project). I think in most cases it's also possible to set a different config option to determine which folder gets used as the parent of the virtualenvs.

Anyways, though typically I'm developing within docker and can get away with some combination of .dockerignore and/or UV_PROJECT_ENVIRONMENT to sidestep this problem, today I was trying to set up UV for the first time on my host machine for package development for something destined for pypi. Because dropbox sometimes locks files while syncing, UV was completely unable to create a virtualenv in the project:

PS D:\Dropbox\Projekte\taev\templatey> uv sync
Resolved 27 packages in 995ms
      Built templatey @ file:///D:/Dropbox/Projekte/taev/templatey
Prepared 2 packages in 2.59s
░░░░░░░░░░░░░░░░░░░░ [0/25] Installing wheels...                                                                                                                                                                                                                                        warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.
         If the cache and target directories are on different filesystems, hardlinking may not be supported.
         If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.
error: Failed to install: ruff-0.9.6-py3-none-win_amd64.whl (ruff==0.9.6)
  Caused by: failed to remove directory `D:\Dropbox\Projekte\taev\templatey\.venv\Lib\site-packages\ruff-0.9.6.data`: Der Prozess kann nicht auf die Datei zugreifen, da sie von einem anderen Prozess verwendet wird. (os error 32)

This would have been a dealbreaker for me, but I really like UV and don't want to revert back to another tool just for package development. So I opted for the nuclear option, and replicated the venv-not-in-project behavior by creating a wrapper around UV that simply sets the UV_PROJECT_ENVIRONMENT based on the current project and then delegates the call to UV:

import hashlib
import os
import subprocess
import sys
from pathlib import Path

import typer

from nix.nix_ import typer_app

ROOT_DIR_FOR_ENVS = Path.home() / '.pyvenv-nix-uv'


def _calculate_project_env_path():
    dir_to_check = Path.cwd()

    # This will search from the CWD up until the root for a pyproject.toml.
    # Note: yes, this skips the root dir, no, we don't care; just make sure
    # you don't ever put your pyproject.toml on your drive root.
    project_path = None
    while (project_dir := dir_to_check).parent != dir_to_check:
        if (project_path := (dir_to_check / 'pyproject.toml')).exists():
            break

    if project_path is None:
        raise RuntimeError('No pyproject found in CWD or parents!')

    project_name = project_dir.name
    # Note: hashing based on pyproject.toml instead of the parent directory,
    # no real reason, is it even possible to rename pyproject.toml?
    project_hash = hashlib.sha256(str(project_path).encode()).hexdigest()
    venv_dirname = f'{project_name}-{project_hash:.5}'
    return ROOT_DIR_FOR_ENVS / venv_dirname


@typer_app.command(
    'uv',
    context_settings={
        'allow_extra_args': True,
        'ignore_unknown_options': True})
def uv_passthrough_with_project_env(ctx: typer.Context):
    """As a workaround to https://github.com/astral-sh/uv/issues/1495,
    this sets UV_PROJECT_ENVIRONMENT based on the first pyproject found
    while walking up from the current working directory and then
    delegates the call to UV via subprocess.
    """
    try:
        return subprocess.run(
            ['uv', *ctx.args],
            check=True,
            env={
                'UV_PROJECT_ENVIRONMENT': str(_calculate_project_env_path()),
                **os.environ})
    except subprocess.CalledProcessError as exc:
        sys.exit(exc.returncode)

That, in turn, was installed as a command in a UV tool called nix, which means that all I need to do for things to "just work" is run nix uv ... (note that templatey-90392 is an example of the result of the hashing behavior I mentioned):

PS D:\Dropbox\Projekte\taev\templatey> nix uv sync
Using CPython 3.13.2
Creating virtual environment at: C:\Users\Niklas\.pyvenv-nix-uv\templatey-90392
Resolved 27 packages in 1.05s
      Built templatey @ file:///D:/Dropbox/Projekte/taev/templatey
Prepared 2 packages in 1.86s
Installed 25 packages in 807ms
 + asttokens==3.0.0
 + colorama==0.4.6
 + decorator==5.1.1
 + executing==2.2.0
 + iniconfig==2.0.0
 + ipython==8.32.0
 + jedi==0.19.2
 + matplotlib-inline==0.1.7
 + mypy==1.15.0
 + mypy-extensions==1.0.0
 + packaging==24.2
 + parso==0.8.4
 + pluggy==1.5.0
 + prompt-toolkit==3.0.50
 + pure-eval==0.2.3
 + pygments==2.19.1
 + pytest==8.3.4
 + refurb==2.0.0
 + ruff==0.9.7
 + stack-data==0.6.3
 + templatey==0.0.0.dev0 (from file:///D:/Dropbox/Projekte/taev/templatey)
 + traitlets==5.14.3
 + typing-extensions==4.12.2
 + wat-inspector==0.4.3
 + wcwidth==0.2.13

[sradc]

Another advantage of having a centralised location is the cleanup; means not having to search for all the .venv dirs.

find ~/ -type d -name ".venv"

[al3xandr3]

@Badg i think you solution is great. Do you plan to make it as an easily available uv tool ?
Would love to use it myself

[thehesiod]

here's my solution, added to my .bashrc (note using g versions since I'm on mac and had to use commands from brew install coretools):

uv_venv() {
    VENV_ROOT=$(greadlink --canonicalize ~/.local/share/uv/venv)
    SRC_ROOT=$(greadlink --canonicalize ~/dev)
    PROJ_REL_PATH=$(grealpath --relative-base=${SRC_ROOT} "${PWD}")
    export UV_PROJECT_ENVIRONMENT="${VENV_ROOT}/${PROJ_REL_PATH}"
}

then you can run uv_venv in the folder you want, then run any uv command you want.

[eabase]

This looks like a promising discussion, TL;DR all yet.
Just filed a similar issues, in ^ above, but not sure if this cover what I had there.

Can someone summarize what points are on the table right now?

UPDATE

My ticket was just closed so pasting my question here:

---

Will this ticket resolve and discuss:

• List all available venv from anywhere.
• List specific project locations that are using those venv's.
• Can activate any of those venv's from any location in the system!
• share venv installs locations between different venv's.
• Keep all venv installations/files (ie. all python packages) on a separate disk.

Be able to list venv's from anywhere?

# lsven

limesdr
llm
lunar
nanovna
osint
stats

And here I created a Powershell comandlet to do the above.
It should be trivial (and simpler) to recreate in bash.

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