UVE is a lightweight Python virtual environment manager that works with UV. It provides a conda-like experience for managing Python virtual environments from any directory, while leveraging UV's speed and reliability.
While I appreciate UV for its clean, per-project virtual environments, it's still convenient at times to have long-lived, general-purpose conda style environments that you can activate from anywhere that aren't tied to an organized project, for general purpose hacking. Since I've completely switched from conda to UV, I created this companion utility to replicate conda-like workflows when needed—giving me the best of both worlds. Why don't I just use Anaconda/conda? See my article Saying Goodbye to Anaconda
- Central storage of virtual environments (similar to conda)
- Create and manage Python environments from any directory
- Cross-platform support (Linux, macOS, Windows)
- Written in Go - no Python dependency for the manager itself
- Simple shell integration for environment activation/deactivation
- Uses UV for fast environment creation
- Automatic shell detection and integration setup
If you are building it yourself, clone the repo and build the binary:
git clone https://github.com/robert-mcdermott/uve.git
cd uve
go build -ldflags="-s -w" -o uve-bin main.goIf you'd rather just use a pre-built binary, download the archive for your platform (OS and architecture) from the releases page and extract the archive to a directory of your choice. Unless you have a reason to select a specific release, choose the latest release.
Linux/macOS:
# Create bin directory if it doesn't exist
mkdir -p ~/bin
# Copy the binary as uve-bin
cp uve-bin ~/bin/uve-bin
# Add to PATH (add this to your .bashrc or .zshrc)
export PATH="$HOME/bin:$PATH"When running uve-bin for the first time on macOS, you may see a security warning as the binary is not signed with an Apple developer certificate. To resolve this:
- When you first try to run
uve-bin, macOS will block it - Open System Settings (Apple menu > System Settings)
- Click on Privacy & Security
- Scroll down to the Security section where you'll see a message about
uve-binbeing blocked - Click "Allow Anyway" to permit the execution
- The next time you run
uve-bin, you may need to click "Open" in a security dialog to confirm
Windows (PowerShell):
# Create directory for binary
mkdir "$env:USERPROFILE\bin" -ErrorAction SilentlyContinue
# Copy the uve-bin.exe binary to your profile
cp uve-bin.exe "$env:USERPROFILE\bin\uve-bin.exe"
# Remove the MOTW flag from the file
Unblock-File -Path "$env:USERPROFILE\bin\uve-bin.exe"
# Add to PATH (permanent, user level)
[Environment]::SetEnvironmentVariable(
"Path",
[Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\bin",
"User"
)UVE includes automatic shell integration with all shell scripts embedded in the binary. Simply run:
uve-bin initNote: running 'uve-bin' should only be used for the initial shell integration when first installing uve, after shell integration is complete, you'll only use the 'uve' command for all other operations
This will:
- Detect your shell type (bash, zsh, or PowerShell)
- Create the appropriate shell integration file
- Update your shell configuration to load UVE automatically
After running uve-bin init, either restart your shell or source your shell configuration file to activate UVE:
Bash:
source ~/.bashrcZsh:
source ~/.zshrcPowerShell:
Import-Module uveCreate a new environment:
uve create myenv [python-version]List all environments:
uve listActivate an environment:
uve activate myenvDeactivate current environment:
uve deactivateDelete an environment:
uve delete myenvShow version of uve you are running:
uve version
Create a new environment with Python 3.12:
uve create ai-stuff 3.12
# output:
Using CPython 3.12.8
Created environment 'ai-stuff' at /home/rmcdermo/.uve/ai-stuffList available environments:
uve list
# output:
Available environments:
- ai-stuff
- base
- test123
- web-stuffActivate an environment:
uve activate web-stuff
# output:
(web-stuff) rmcdermo:~/mycode/uve$Verify activation
which python # or `Get-Command python` on PowerShell
# output:
/home/rmcdermo/.uve/web-stuff/bin/pythonInstall packages in the activated environment using UV's pip command
uv pip install numpy pandas
# output:
Using Python 3.11.11 environment at: .uve/web-stuff
Resolved 6 packages in 763ms
Prepared 3 packages in 1.31s
Installed 6 packages in 239ms
+ numpy==2.2.3
+ pandas==2.2.3
+ python-dateutil==2.9.0.post0
+ pytz==2025.1
+ six==1.17.0
+ tzdata==2025.1View installed packages
uv pip list
#output:
Using Python 3.11.11 environment at: .uve/web-stuff
Package Version
--------------- -----------
numpy 2.2.3
pandas 2.2.3
python-dateutil 2.9.0.post0
pytz 2025.1
six 1.17.0
tzdata 2025.1Deactivate the current environment
uve deactivateDelete an environment (must be deactivated first):
uve delete test123
# output:
Deleted environment 'test123'Environments are stored in ~/.uve by default. You can change this location by setting the UVE_HOME environment variable:
export UVE_HOME="/path/to/environments"By default, environments are created in ~/.uve/<env-name> with the following structure:
~/.uve/
├── env1/
│ ├── bin/ # Scripts and executables
│ ├── lib/ # Python packages
│ └── pyvenv.cfg # Environment configuration
└── env2/
└── ...
UVE manages Python virtual environments in a central location (~/.uve by default) and provides shell functions for activating/deactivating these environments. When you activate an environment:
- Your original PATH is saved
- The environment's bin/Scripts directory is added to PATH
- VIRTUAL_ENV is set to the environment path
When deactivating:
- Original PATH is restored
- Environment variables are cleaned up
-
command not found: uve- Ensure the binary is in your PATH
- Run
uve-bin initto set up shell integration - Restart your terminal or source your shell config
-
Activation not working
- Make sure you've run
uve-bin initand restarted your shell - For PowerShell: Run
Import-Module uvein the current session
- Make sure you've run
-
UV not found
- Install UV
-
Package installation errors
- Make sure you've activated the environment first
- Use
uv pip installinstead of regularpip install
UVE_HOME: Custom location for environmentsVIRTUAL_ENV: Set by activation (don't set manually)UVE_OLD_PATH: Stores original PATH during activation
Contributions are welcome! Please feel free to submit a Pull Request.
- UV - The underlying Python package installer
- Inspired by conda's environment management approach