Setting Up a Scientific Python Environment using venv
A guide to creating a reproducible scientific Python environment on macOS (or Linux).
venv
This guide walks through creating a dedicated scientific Python environment called numerics, installing common scientific packages, and making the environment available inside Jupyter notebooks.
The instructions assume:
- You are running macOS on Apple Silicon (M1/M2/M3) or a Linux based OS
- You Python installed via Homebrew
- You have a terminal application available
1. Check Your Python Installation
Before creating an environment, verify that Python is installed and available from Homebrew.
1
2
python3 --version
which python3
Expected output:
1
2
Python 3.14.x
/opt/homebrew/bin/python3
If Python is not installed through Homebrew, install it first:
1
brew install python
Note on multiple installations: If which python3 does not point to /opt/homebrew/bin/python3, or python3 --version does not show you the desired version number, you likely have multiple versions on your system. Run which -a python3 to see all locations, or use ls /opt/homebrew/bin/ | grep python to find the specific Homebrew-managed command. To avoid ambiguity, you can invoke the correct version directly by its full name (e.g., python3.14).
2. Create a Dedicated Virtual Environment
Using a virtual environment keeps scientific packages isolated from the system Python installation.
Create a directory to store virtual environments:
1
mkdir -p ~/venvs
Create the environment:
1
python3 -m venv ~/venvs/numerics
Activate it:
1
source ~/venvs/numerics/bin/activate
Your shell prompt should now begin with:
1
(numerics)
Confirm that Python is coming from the virtual environment:
1
which python
Expected output:
1
/Users/subhodeep/venvs/numerics/bin/python
3. Upgrade Packaging Tools
Upgrade the package-management tools before installing scientific software:
1
pip install --upgrade pip setuptools wheel
Verify:
1
pip --version
4. Create a Requirements File
Create a file named:
1
~/numerics-requirements.txt
Populate it with the packages you want installed.
Example:
1
2
3
4
5
6
7
8
numpy
scipy
pandas
matplotlib
seaborn
numba
ipykernel
jupyterlab
5. Install the Scientific Stack
Install all packages listed in the requirements file:
1
pip install -r ~/numerics-requirements.txt
Depending on the number of packages and internet speed, installation may take several minutes.
Occasionally you may see messages such as:
1
WARNING: Cache entry deserialization failed, entry ignored
These warnings are generally harmless and can be ignored.
Some packages in the scientific stack (like h5py) require C-based system libraries to be present on the machine. Before installing the requirements, run:
1
2
3
4
5
6
7
8
9
10
11
12
13
brew install hdf5
---
## 6. Register the Environment with Jupyter
Register the virtual environment as a Jupyter kernel so it appears as a selectable notebook kernel.
```bash
python -m ipykernel install \
--user \
--name numerics \
--display-name "Python (numerics)"
After completion, Jupyter notebooks will offer:
1
Python (numerics)
as a kernel option.
7. Test the Installation
Launch an interactive Python session:
1
python
Run:
1
2
3
4
5
6
7
8
import numpy
import scipy
import pandas
import matplotlib
import seaborn
import numba
print("OK")
Expected output:
1
OK
Exit Python:
1
quit()
8. Verify Jupyter Kernel Registration
List all installed Jupyter kernels:
1
jupyter kernelspec list
Example output:
1
2
3
4
Available kernels:
numerics
julia-1.12
wolframlanguage13.3
The exact list will depend on your machine.
9. Daily Usage
Activate the environment whenever you want to work in it:
1
source ~/venvs/numerics/bin/activate
Deactivate when finished:
1
deactivate
Install additional packages later:
1
pip install PACKAGE_NAME
Upgrade a specific package:
1
pip install --upgrade PACKAGE_NAME
Check for outdated packages:
1
pip list --outdated
10. Create a Reproducible Snapshot
Save the exact package versions currently installed:
1
pip freeze > ~/numerics-lock.txt
The generated file can later be used to recreate the environment exactly:
1
pip install -r ~/numerics-lock.txt
This is useful for reproducible research, sharing environments with collaborators, and recovering a working setup after system upgrades.
11. Create a Quick-Access Alias
To jump into your scientific environment from any terminal directory, add an alias to your shell configuration file.
Open your .zshrc file:
1
2
nano ~/.zshrc
Add this line to the bottom:
1
2
3
# Scientific Python Environment
alias numerics='source ~/venvs/numerics/bin/activate'
Save, exit, and reload:
1
2
source ~/.zshrc
Now, simply type numerics in any terminal to jump into your workspace.
Useful Commands
Show Installed Packages
1
pip list
Display Environment Location
1
which python
Display Package Details
1
pip show numpy
Remove the Environment Completely
1
rm -rf ~/venvs/numerics
Remove the Jupyter Kernel
1
jupyter kernelspec uninstall numerics
Requirements File (numerics-requirements.txt)
Create this file in your home directory (~/) , this file defines the full scientific stack that will be installed:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
# Core & High-Performance
numpy
scipy
numba
numexpr
joblib
psutil
# Data Analysis & Storage
pandas
xarray
dask
h5py
tables
zarr
# Visualization
matplotlib
seaborn
plotly
# Math & Symbolic
sympy
uncertainties
mpmath
# Statistics & Inference
statsmodels
scikit-learn
emcee
corner
lmfit
# Domain Specific
astropy
# Interoperability
juliacall
wolframclient
# Terminal & Formatting
tabulate
prettytable
rich
tqdm
# Jupyter
jupyterlab
ipykernel