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: 30–60 minutes, mostly waiting for downloads.

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

Having any version of Python is not enough. The workshop requires Python 3.11, 3.12, or 3.13 specifically. If python3 --version shows Python 3.9 or 3.10, you still need to install 3.12.

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 — Download the workshop files

The workshop files live on GitHub. You need to download them to your computer before you can do anything else.

Choose a location on your computer where you want to keep the workshop — somewhere you will remember and that has enough free space (at least 15 GB recommended). Common choices are your home folder, Desktop, or an external drive.

Then run this command, replacing /path/to/your/folder with the actual path to where you want it:

cd /path/to/your/folder

For example:

If you want it in Downloads: cd /Users/$(whoami)/Downloads
If you want it on your Desktop: cd /Users/$(whoami)/Desktop
If you want it in your home folder: cd /Users/$(whoami)
If you want it on an external drive: cd /Volumes/MyDrive

Then download the workshop:

git clone https://github.com/miniscope/workshop-processing-and-analysis.git

This creates a folder called workshop-processing-and-analysis wherever you ran the command. Navigate into it:

cd workshop-processing-and-analysis

Your prompt should now include workshop-processing-and-analysis. This is your workshop folder — remember where it is, as you will navigate back to it every time you use the workshop.

Disk space: The workshop data files are large. Make sure the location you choose has at least 15 GB free before continuing. To check how much space you have available, run df -h / and look at the number under Avail.

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).

Make sure you are inside the workshop folder (your prompt should show workshop-processing-and-analysis), then run:

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.

You must run this activation command every time you open a new Terminal window before using the workshop. If you skip it, commands will fail or use the wrong packages.

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 the tutorial notebooks

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

python scripts/fetch_notebooks.py

Step 8 — Download the workshop data

The workshop dataset (miniscope video, behavior video, and timestamps) is hosted on UCLA Dataverse and downloaded automatically by the following command:

python scripts/get_data.py

This downloads everything — raw recordings and all pre-processed stages — and places them under data/sessions/prerecorded/. This step can take 10–30 minutes depending on your internet connection, as it includes large video files. A progress meter will show you how much has downloaded.

What gets downloaded

data/sessions/prerecorded/
├── raw/          miniscope video, behavior video, timestamps
├── minian_out/   pre-processed Minian output (calcium traces, footprints)
├── deconv_out/   pre-processed deconvolved activity
└── eztrack_out/  pre-processed behavioral tracking

Download options

If you are short on disk space or do not plan to run every stage yourself, you can download only what you need:

Command	What it downloads	Approx. size
`python scripts/get_data.py`	Everything (raw + all processed stages)	~6 GB
`python scripts/get_data.py --what raw`	Raw video and timestamps only (needed to run Minian yourself)	~4 GB
`python scripts/get_data.py --what processed`	Pre-processed outputs only (skip running Minian/eztrack)	~230 MB
`python scripts/get_data.py --what minian_out`	Just the Minian output (one specific stage)	~222 MB
`python scripts/get_data.py --force`	Re-download everything even if files already exist	—

Running low on disk space? The raw videos alone are ~4 GB, and Minian needs additional temporary space (roughly 2–3× the video size) while it runs. If you are tight on space, download only the processed outputs with --what processed — you can still run the deconvolution and capstone stages without the raw videos. To check your available space: df -h / and look at the Avail column.

The script is local-first: if you have already run a stage yourself (e.g. you ran Minian on your own), that output is kept and only the missing stages are downloaded. You will not lose your own results by running this command.

Step 9 — 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, open Terminal and navigate to wherever you put the workshop folder, then run:

cd /path/to/your/workshop-processing-and-analysis
source .venv/bin/activate
jupyter lab

If you are not sure where you put it, run this to find it:

find /Users/$(whoami) -maxdepth 4 -name "workshop-processing-and-analysis" -type d 2>/dev/null

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.

command not found: git: Run xcode-select --install to install git, then try the clone command 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

FileNotFoundError when opening the Minian notebook: The data has not been downloaded yet. Run python scripts/get_data.py and wait for it to complete before re-opening the notebook.

get_data.py fails or stalls mid-download: Check your internet connection, then re-run python scripts/get_data.py --force to retry. The script will overwrite any incomplete files.

OSError: No space left on device during Minian: Your disk filled up during processing. Delete the incomplete intermediate files (rm -rf data/sessions/prerecorded/minian_intermediate), free up space, and rerun. Minian needs roughly 2–3× the size of your input videos in temporary disk space while it runs.