Why virtual environments?
When you installed SuPy with pip3 install supy, you may have encountered permission errors—or you succeeded but wonder if there’s a better way.
There is. Virtual environments solve three problems:
- Permission issues: Install packages without admin rights
- Project isolation: Different projects can use different package versions without conflicts
- Reproducibility: Share your exact setup with collaborators
An analogy: Imagine your computer is a shared kitchen. Installing Python packages globally is like putting all your ingredients in the communal fridge—others might move them, use them up, or replace them with incompatible versions. A virtual environment is your own mini-fridge in your room. Everything you need for your SUEWS recipe stays exactly where you put it, untouched by other projects.
Why uv?
The traditional tool is venv (built into Python). It works, but it’s slow.
uv is a modern replacement that’s:
- 10-100x faster than pip and venv
- Single tool for Python installation, environments, and packages
- Just works on Mac, Windows, and Linux
We recommend uv for all new SUEWS users.
Installing uv
Mac / Linux
Open a terminal and run:
curl -LsSf https://astral.sh/uv/install.sh | sh
Close and reopen your terminal, then verify:
uv --version
Windows
Open PowerShell and run:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Close and reopen PowerShell, then verify:
uv --version
Creating a SUEWS environment
Navigate to where you want your SUEWS project:
Mac / Linux:
cd ~/Documents
mkdir suews-project
cd suews-project
Windows (PowerShell):
cd ~\Documents
mkdir suews-project
cd suews-project
Create a virtual environment with Python 3.11:
uv venv --python 3.11
This creates a .venv folder containing an isolated Python installation.
Activating the environment
Before working, activate the environment:
Mac / Linux:
source .venv/bin/activate
Windows (PowerShell):
.venv\Scripts\Activate.ps1
Your prompt changes to show (.venv) — you’re now in the isolated environment.
Installing SuPy
With the environment active:
uv pip install supy matplotlib
Notice how fast it is? uv caches packages, so reinstalls are nearly instant.
Running your simulation
Now run Python:
python
And use the same code from the beginner’s guide:
from supy import SUEWSSimulation
sim = SUEWSSimulation.from_sample_data()
output = sim.run()
print(output.QH.head())
Deactivating
When you’re done:
deactivate
This works on all platforms. Your prompt returns to normal. The environment stays on disk—just activate it again next time.
Quick reference
Create environment:
uv venv --python 3.11
Activate:
- Mac/Linux:
source .venv/bin/activate - Windows:
.venv\Scripts\Activate.ps1
Install packages:
uv pip install supy matplotlib pandas
Deactivate:
deactivate
Delete environment (start fresh):
- Mac/Linux:
rm -rf .venv - Windows:
Remove-Item -Recurse -Force .venv
Sharing your environment
To share your exact package versions:
uv pip freeze > requirements.txt
Others can recreate it:
uv venv --python 3.11
Then activate (see above for your platform) and install:
uv pip install -r requirements.txt
Troubleshooting
“uv: command not found” (or “not recognized” on Windows)
Close and reopen your terminal after installing uv.
“Python 3.11 not found”
uv can install Python for you:
uv python install 3.11
Forgot to activate?
If python shows the wrong version or packages are missing, you probably forgot to activate. Run the activation command again.
Summary
Using uv takes an extra minute to set up, but saves hours of debugging later. Your SUEWS work stays isolated, reproducible, and conflict-free.
Questions? Post below—happy to help.