Guide/Install Miniscope Workshop Processing and Analysis Pipeline on Mac

Git repo: https://github.com/miniscope/workshop-processing-and-analysis

This guide walks you through installing everything you need to run the Miniscope Workshop on a Mac, starting from scratch. You do not need any prior experience with Terminal or programming. Follow every step in order.

Estimated time: 20–30 minutes, mostly waiting for things to download.

What you will install

Tool	What it does	Do you need it?
Homebrew	A package manager — makes installing software on Mac easy	Required
Python 3.12	The programming language the workshop runs in	Required (must be 3.11–3.13)
ffmpeg	A video processing tool the workshop needs in the background	Required
Virtual environment	An isolated workspace so workshop packages don't conflict with other software on your computer	Required
Jupyter Lab	The browser-based interface where you open and run the workshop notebooks	Installed automatically

Before you start — Check what you already have

You may already have some of these tools. Check first so you don't reinstall anything unnecessarily.

1. Open Terminal

Terminal is a program already on your Mac. It lets you type commands directly to your computer.

Press Cmd + Space to open Spotlight Search
Type Terminal and press Enter

A window will open with a blinking cursor. Leave it open — you will use it throughout this guide.

How Terminal works: Paste a command, press Enter to run it, and wait for the prompt to come back (it looks like yourname@macbookair ~ %). If a command prints nothing, that means it worked — silence is normal.

2. Run these checks

Paste each command below into Terminal and press Enter. Read what appears and follow the instruction next to it.

Check for Homebrew:

brew --version

See Homebrew 4.x.x → you already have it, skip Step 1
See command not found: brew → you need to install it, do Step 1

Check for Python 3.12:

python3.12 --version

See Python 3.12.x → you already have it, skip the Python part of Step 2
See command not found: python3.12 → you need to install it, do Step 2

Check for ffmpeg:

ffmpeg -version

See a line starting with ffmpeg version → you already have it, skip the ffmpeg part of Step 2
See command not found: ffmpeg → you need to install it, do Step 2

Template:Note

Step 1 — Install Homebrew

Homebrew is a free tool that makes it easy to install software on a Mac. You only ever need to install it once.

Paste this into Terminal and press Enter:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

What to expect:

It will ask for your Mac login password — type it and press Enter. You will not see the characters appear as you type. That is normal.
It may ask you to press Enter to confirm. Do so.
It will download and install for 1–3 minutes.
You will know it is done when you see: ==> Installation successful!

After it finishes, run these three commands one at a time (press Enter after each):

echo >> /Users/$(whoami)/.zprofile

echo 'eval "$(/opt/homebrew/bin/brew shellenv zsh)"' >> /Users/$(whoami)/.zprofile

eval "$(/opt/homebrew/bin/brew shellenv zsh)"

None of these will print anything. That means they worked.

Step 2 — Install Python 3.12 and ffmpeg

Now use Homebrew to install Python and ffmpeg in one command:

brew install python@3.12 ffmpeg

This takes a few minutes. A lot of text will scroll by — just wait until your prompt comes back.

Verify both installed correctly:

python3.12 --version && ffmpeg -version | head -1

You should see:

Python 3.12.13
ffmpeg version 8.x.x ...

If you see both lines, you are ready to continue.

Step 3 — Navigate to the workshop folder

Tell Terminal to go to the folder where the workshop files are:

cd /Users/$(whoami)/Downloads/workshop-processing-and-analysis-main

Your prompt should now include workshop-processing-and-analysis-main. This means you are in the right place.

Step 4 — Create a virtual environment

A virtual environment is an isolated container for the workshop's packages. It keeps everything self-contained so the workshop doesn't interfere with other software on your computer (and vice versa).

python3.12 -m venv .venv

No output means it worked.

Step 5 — Activate the virtual environment

source .venv/bin/activate

Your prompt will now start with (.venv) — this tells you the environment is active and you are working inside it.

Template:Note

Step 6 — Install the workshop packages

First, upgrade pip (the tool that installs Python packages):

python -m pip install --upgrade pip

Then install all the workshop packages. This step takes 5–10 minutes — it is downloading a large scientific software stack:

python -m pip install -r requirements.txt

A lot of text will scroll by. Just wait. When your prompt comes back, it is done.

Step 7 — Register the Jupyter kernel and fetch content

These three commands set up the workshop's Jupyter kernel, download the tutorial notebooks, and fetch the example data. Run them one at a time:

python -m ipykernel install --user --name workshop --display-name "Workshop"

python scripts/fetch_notebooks.py

python scripts/get_data.py

Step 8 — Launch Jupyter Lab

jupyter lab

A browser window will open automatically. You will see the Jupyter Lab interface with your workshop files listed in the left panel.

Using Jupyter Lab

The left panel shows your workshop folders: tutorials, data, capstone
Click into tutorials and navigate to the module you want to work on
Open any file ending in .ipynb — these are the interactive notebooks
If asked which kernel to use, always choose Workshop — never "Python 3 (ipykernel)"

Every time you come back

You only need to go through the full installation once. The next time you want to use the workshop, just open Terminal and run these three lines:

cd /Users/$(whoami)/Downloads/workshop-processing-and-analysis-main
source .venv/bin/activate
jupyter lab

Troubleshooting

command not found: brew: Close Terminal completely and reopen it, then try again. Homebrew requires a fresh Terminal window after installation to be recognized.

command not found: python3.12: Close Terminal and reopen it, then run brew install python@3.12 ffmpeg again.

Jupyter opens but the "Workshop" kernel is not listed: You likely skipped activating the virtual environment. Close Jupyter, make sure you see (.venv) in your prompt (run source .venv/bin/activate if not), then re-run Step 7 and launch Jupyter again.

The browser did not open automatically: Look in Terminal for a line containing http://localhost:8888/ and paste that address into your browser manually.

An error appears during pip install -r requirements.txt: Make sure (.venv) is showing in your prompt before running the command. If it is not, activate the environment first: source .venv/bin/activate