macOS setup

macOS setup#

Complete this setup before class if you can. You need an internet connection, permission to install software for your account, and about 10 GB of free space. The same course files support Apple Silicon and Intel Macs, but both routes still require a platform pilot.

1. Identify your Mac and open Terminal#

Choose Apple menu → About This Mac. Record the macOS version and chip:

  • Apple M1, M2, M3, M4, or later means Apple Silicon.

  • Intel in the processor name means an Intel Mac.

This information helps diagnose package or movie-export problems. Next open Finder → Applications → Utilities → Terminal. A line ending in % or $ is the prompt. Type only the command itself, then press Return.

If your organization manages the Mac and blocks installation, stop and contact its support staff or the workshop instructor. You should not need sudo for this setup.

2. Install uv#

uv installs Python and the packages recorded for the workshop. Copy the following command from the official uv installation page, paste it into Terminal, and press Return:

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

curl downloads the official installer, and sh runs it. Close Terminal, reopen it, and check the installation:

uv --version

Success looks like uv 0.x.y (the numbers may differ). If Terminal says command not found, close every Terminal window and try once more, then see troubleshooting.

3. Download and extract the workshop folder#

Download the workshop ZIP supplied by your instructor or use the repository’s Code → Download ZIP button. Safari normally expands a ZIP automatically in Downloads. If it does not, double-click the ZIP in Finder.

Move the resulting folder to Documents. Open it and confirm that it directly contains README.md, pyproject.toml, uv.lock, notebooks, and scripts. GitHub may name it napari-workshop-main; that name is fine.

4. Move Terminal into the folder#

Type cd followed by one space, drag the extracted folder from Finder into Terminal, and press Return. Dragging inserts the exact path and safely handles spaces. Then list the folder:

pwd
ls

pwd prints your current folder. ls should show pyproject.toml, uv.lock, notebooks, and scripts. If it does not, locate the folder that directly contains those files.

An equivalent typed command is below; quotation marks keep a path with spaces together:

cd "$HOME/Documents/napari-workshop-main"

5. Create the workshop environment#

uv sync --locked

uv sync creates a private .venv environment inside this workshop folder and installs its packages. --locked requires the tested versions recorded in uv.lock. uv may first download Python 3.12. The first run can take several minutes.

Success ends without red error text and leaves a hidden .venv folder. You do not need to activate it. Register this environment as a Jupyter kernel:

uv run python -m ipykernel install --user --name napari-workshop --display-name "Python (napari workshop)"

This uses Python from .venv and creates the kernel choice Python (napari workshop). Success includes a message beginning Installed kernelspec.

6. Download and check the data#

Follow Download the data. The recommended command is:

uv run scripts/download_data.py --dataset teaching

Run the non-graphical checks:

uv run python scripts/check_setup.py

Success lists a Python executable inside this workshop’s .venv, napari 0.6.6 and other package versions, available RAM, and Checks complete. The exact folder and RAM number vary by computer.

Then test a tiny napari window:

uv run python scripts/check_setup.py --gui

A separate napari window should appear. Close it after the test. Add --movie only when the instructor asks you to test movie export. If macOS asks whether Terminal may access Documents, allow access for this workshop folder.

7. Start JupyterLab#

uv run jupyter lab

Terminal prints messages and opens JupyterLab in your web browser. Leave Terminal running. In the browser, double-click notebooks, then 00_check_setup.ipynb. At the upper right, select Python (napari workshop). Choose Run → Run All Cells and compare each result with the notebook’s explanation.

The browser cannot display a local Qt application by itself. Napari opens in a separate desktop window; use Command+Tab or check behind the browser if it is hidden.

To finish, save the notebook with File → Save Notebook, close napari, and choose File → Shut Down in JupyterLab. Close Terminal after the command stops. On another day, open Terminal, return to the workshop folder, and run uv run jupyter lab again.

These directions have not yet been certified on Apple Silicon or Intel macOS. Record the macOS version, chip, and exact error text if a step fails. A successful install does not by itself prove that 3D graphics or MP4 export works.