Is there a way to configure uv to store all virtual environments in a central location…
- User
Is there a way to configure
uvto store all virtual environments in a central location instead of in the application folders? - Assistant
Of course! This is a very common workflow, and
uvsupports it by adopting the same convention used by the popularvirtualenvwrappertool.Yes, you can configure
uvto store virtual environments in a central location by setting theWORKON_HOMEenvironment variable.When this variable is set,
uvwill use that directory as the base for creating new named virtual environments.How to Configure Centralized Virtual Environments
Here is a step-by-step guide to set it up.
1. Choose and Create a Central Directory
First, decide where you want to store all your virtual environments. A common choice is a hidden directory in your home folder, like
~/.virtualenvs.Create this directory if it doesn't exist:
mkdir -p ~/.virtualenvs2. Set the
WORKON_HOMEEnvironment VariableYou need to tell your shell where this central directory is. You do this by setting the
WORKON_HOMEenvironment variable.To set it for your current terminal session, you can run:
export WORKON_HOME=~/.virtualenvsTo make this setting permanent, you need to add this line to your shell's startup file.
-
For Bash: Add it to
~/.bashrcor~/.bash_profile.echo 'export WORKON_HOME=~/.virtualenvs' >> ~/.bashrc source ~/.bashrc # To apply changes to the current session -
For Zsh (common on macOS): Add it to
~/.zshrc.echo 'export WORKON_HOME=~/.virtualenvs' >> ~/.zshrc source ~/.zshrc # To apply changes to the current session -
For Fish: Use the
setcommand in~/.config/fish/config.fish.# in ~/.config/fish/config.fish set -x WORKON_HOME ~/.virtualenvs
3. How to Use It with
uvNow that
WORKON_HOMEis set, the behavior ofuv venvchanges slightly.-
Without a name:
uv venvwill still create a.venvin the current directory. This is the default, project-local behavior.cd my-app-folder uv venv # Creates ./my-app-folder/.venv -
With a name: This is where
WORKON_HOMEis used. If you provide a name for your environment,uvwill create it inside your central directory.cd my-app-folder # This will create the environment at ~/.virtualenvs/my-app uv venv my-app # To check: ls ~/.virtualenvs # Output will include "my-app"
Practical Workflow
Here’s what a typical workflow looks like with this setup:
-
Navigate to your project folder:
cd ~/projects/my-cool-api -
Create a named virtual environment:
# This creates the environment in $WORKON_HOME/my-cool-api-env uv venv my-cool-api-env -
Activate the environment: You still need to activate the environment using its full path.
uvdoes not (yet) have aworkoncommand likevirtualenvwrapper.source $WORKON_HOME/my-cool-api-env/bin/activate # Your prompt will change, e.g., (my-cool-api-env) $ -
Install packages: Now you can use
uvto install packages into your activated, centralized environment.uv pip install fastapi "uvicorn[standard]"
Comparison: Centralized vs. Project-Local
Why use a central location? (
WORKON_HOME)- Cleaner Project Directories: Your project folder isn't cluttered with a
.venvdirectory. This is useful if you don't want it showing up in file searches or version control (even if it's in.gitignore). - Easy to Find/Manage All Envs: You can simply
ls ~/.virtualenvsto see every virtual environment you've created on your system. - Name Reuse: Not generally recommended, but you could potentially use the same environment for multiple small, related projects.
Why use the default project-local location? (
.venv)- IDE/Tooling Integration: This is the biggest advantage. Tools like VS Code, PyCharm, and others are configured to automatically detect a
.venvfolder in your project's root. With a central location, you often have to manually configure your editor to find the Python interpreter for each project. - Self-Contained Projects: Everything the project needs is inside its folder. When you delete the project folder, you also delete its environment.
- No Name Clashes: You never have to worry about two projects wanting the same environment name (e.g.,
api). Each one has its own.venv.
Summary
Method Command Result Best For Project-Local (Default) uv venvCreates ./.venvSimplicity, excellent IDE support, and self-contained projects. Centralized (Configured) uv venv <env-name>Creates $WORKON_HOME/<env-name>Keeping project folders clean and managing all envs in one place. Manual One-Off uv venv /path/to/envCreates an environment at a specific path Scripts or specific cases where you need full control over the location. -
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.