Skip to content

Virtual environments

Due to the vast number of Python packages available and different packages requiring different versions, we strongly recommend working in a virtual environment.

Support for environment managers

We provide full support for uv-based installations. While we document other tools (pipenv, venv) below, please note that you'll need to troubleshoot issues with these tools on your own.

Why use virtual environments?

A virtual environment creates an isolated Python environment for each project, which means:

  • No conflicts: Different projects can use different versions of the same package
  • Clean dependencies: Each project only includes the packages it needs
  • Reproducibility: Others can easily recreate your exact environment
  • Safety: Experimenting with packages won't break your system Python

It's best practice to always use a virtual environment for Python projects.

uv is our recommended tool for managing Python projects. It's fast, modern, and handles Python versions, virtual environments, and dependencies all in one tool.

Basic workflow with uv

Navigate to your project folder (or create it):

mkdir -p ~/projects/myproject
cd ~/projects/myproject

Initialize a new project:

uv init

This creates:

  • pyproject.toml - project configuration and dependencies
  • main.py - starter Python script
  • .python-version - specifies the Python version for this project
  • .venv/ - virtual environment (created automatically when needed)
  • uv.lock - lock file ensuring reproducible installations (created when adding packages)

Add packages:

uv add numpy pandas matplotlib

Run your code:

uv run main.py

Note: uv run replaces the traditional python command - it automatically activates your environment and runs your script.

Working with an existing project (has pyproject.toml):

cd existing-project
uv sync  # Installs all dependencies automatically
uv run main.py

uv cheat sheet

# Install specific Python version
uv python install 3.14

# Create new project
uv init myproject

# Add packages
uv add numpy matplotlib scipy sund

# Remove package
uv remove scipy

# See dependency tree
uv tree

# Run script (auto-activates environment)
uv run main.py

# Pin project to specific Python version
uv python pin 3.14

# Run CLI tools
uvx ruff  # or: uv tool run ruff

# Update uv itself
uv self update

Troubleshooting uv

uv complains that the environment is shadowed

uv can detect uv projects in parent directories. If you accidentally created an environment in a parent folder, you need to remove it.

Look for and delete uv.lock and .venv/ in parent directories:

Often found in C:\Users\<user>\ if created from the default terminal location.

Use File Explorer to navigate and delete. You may need to enable "Show hidden files" to see .venv/.

Often found in ~ (your home directory) if created from the default terminal location.

In Finder: Go → Home, then enable showing hidden files (Cmd+Shift+.).

Or use terminal: 

rm -rf ~/uv.lock ~/.venv/

Often found in ~ if created from the default terminal location.

rm -rf ~/uv.lock ~/.venv/
Do not create environments in cloud storage

Creating Python environments in cloud-synced folders (OneDrive, iCloud, Dropbox) often causes issues. File locking and syncing can corrupt the environment.

Store projects in: ~/projects/ or C:\Users\<user>\projects\ instead.

Alternative: Pipenv

Pipenv is another popular environment manager that creates isolated environments per project.

Installing pipenv

pip install pipenv

(Use pip3 on some systems if pip is not available)

Basic workflow with pipenv

Navigate to your project folder:

mkdir -p ~/projects/myproject
cd ~/projects/myproject

Create and activate environment:

pipenv shell

This creates a virtual environment named after the folder and activates it. Your prompt will change to show you're in the environment.

Install packages:

pipenv install numpy pandas matplotlib

Run your code (inside the environment):

python main.py

Exit the environment:

exit

Useful pipenv commands

# Create/activate environment
pipenv shell

# Install package
pipenv install requests

# Install dev dependencies  
pipenv install --dev pytest

# Install from requirements.txt
pipenv install -r requirements.txt

# Uninstall package
pipenv uninstall requests

# Remove entire environment
pipenv --rm

# Show dependency graph
pipenv graph

# Run command in environment without activating
pipenv run python main.py

Alternative: venv

venv is Python's built-in virtual environment tool. It's simpler than uv or pipenv but requires more manual management.

Basic workflow with venv

Navigate to your project folder:

mkdir -p ~/projects/myproject
cd ~/projects/myproject

Create the environment:

python3 -m venv .venv

Activate the environment:

PowerShell/Terminal: 

.venv\Scripts\Activate.ps1

Command Prompt: 

.venv\Scripts\activate


source .venv/bin/activate

source .venv/bin/activate

Your prompt will change to show (.venv) when activated.

Install packages:

pip install numpy pandas matplotlib

Run your code:

python main.py

Deactivate the environment:

deactivate

Managing dependencies with venv

Since venv doesn't automatically track dependencies, you should manually maintain a requirements.txt file:

Create requirements file:

pip freeze > requirements.txt

Install from requirements file:

pip install -r requirements.txt

Tips for venv

  • Always activate before installing packages or running code
  • Use .gitignore: Add .venv/ to your .gitignore file so the environment isn't committed to git
  • Document dependencies: Keep requirements.txt updated and committed to version control
  • The folder name .venv is conventional but you can use any name

~~Anaconda and Conda~~ (Deprecated)

Update: We no longer recommend using Anaconda due to licensing changes that make it non-free for academic use. Use uv, pipenv, or venv instead.

If you're already using conda, you can continue, but for new projects we recommend switching to uv.