This is a short, practical guide for new lab members setting up Python + Jupyter on their own laptop (especially MacBook) using uv.

Official references:

1) Install uv

macOS / Linux (official installer)

curl -LsSf https://astral.sh/uv/install.sh | sh

If you use Homebrew on macOS:

brew install uv

Restart terminal, then verify:

uv --version

2) Install Python with uv

uv python install 3.11

You can check installed Python versions:

uv python list

3) Create a project and virtual environment

mkdir lab-python
cd lab-python
uv init
uv venv --python 3.11
source .venv/bin/activate

4) Install Jupyter and common scientific packages

uv pip install jupyterlab ipykernel numpy pandas scipy matplotlib

5) Register a Jupyter kernel for this environment

python -m ipykernel install --user --name lab-python --display-name "Python (lab-python)"

6) Start JupyterLab

jupyter lab

Open the URL shown in terminal (usually http://localhost:8888/...).

7) Daily workflow

cd ~/path/to/lab-python
source .venv/bin/activate
jupyter lab

When done:

deactivate

8) Share/reproduce environment

Export dependencies:

uv pip freeze > requirements.txt

Set up on another machine:

uv python install 3.11
uv venv --python 3.11
source .venv/bin/activate
uv pip install -r requirements.txt

9) Common issues

  • uv: command not found → restart terminal, then re-check PATH.
  • Wrong Python version in notebook → activate .venv and re-run ipykernel install.
  • Package conflicts → create a fresh project folder and a new .venv.

10) Lab recommendation

Use one project = one .venv. This keeps dependencies clean and reproducible for collaboration.