(installation)=
For the best experience, we recommend installing and running napari on your local machine.
However, if you prefer to not install anything locally, you can run the workshop in the cloud:
* If you are at SciPy 2025, you can use the SciPy 2025 Nebari JupyterHub instance to run everything in the cloud. For instructions, please see [our Nebari guide](nebari).
* If the Nebari instace is no longer available, you also have the option of [running everything in the cloud using Binder](/napari-scipy2025-workshop/napari-workshops/docs/launching_binder.html). Please note that performance, particularly 3D rendering, will be severely limited on this free resource!
napari is a Python application and package, so it requires a working Python installation. There are multiple ways that Python installations and packages can be managed. For a detailed breakdown, we recommend this excellent guide and tutorial by Talley Lambert (Harvard Medical School).
For the purposes of this workshop, for consistency, we will use [`conda`](https://docs.conda.io/en/latest/) as the Python, package, and environment manager. However, you can use your own, preferred method to install `napari`, `PyQt5`, and `jupyterlab` into a virtual environment with Python 3.12. Please refer to the [napari installation documentation](https://napari.org/stable/tutorials/fundamentals/installation.html).
condaIn this tutorial, we will install Python via miniforge, a distribution of Python based in the conda package manager.
If you already have anaconda, miniconda, or miniforge installed, those will work
as well. You can check using:
```bash
conda info
```
However, we recommend you that the conda version is >23.10 and that you are using
[`conda-forge` channels](https://conda-forge.org/docs/user/introduction/). You can ensure this using:
```bash
conda update conda
conda config --add channels conda-forge
```
Once you have that set, you can skip to [the next section](setting-up-your-napari-workshop-environment).
Click on the tile corresponding to your platform (e.g., Windows, macOS, or Linux) to download the installer. If you are unsure about your macOS or Linux architecture, open a command line terminal and run:
uname -m
Alternately, you can also download the installer using the command line on macOS or Linux by running:
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
Once you have downloaded miniforge installer, run it to install conda. Note: you may need admin permissions during the installation process.
Miniforge3-Windows-x86_64.exe.Miniforge3-MacOSX-arm64.sh or Miniforge3-Linux-x86_64.sh.cd ~/Downloads
bash Miniforge3-$(uname)-$(uname -m).sh
The installer will walk you through a series of prompts to complete the installation. We recommend that you use the default installation location, but you can change it to a different location in your user directory if you prefer.
Once the installation finishes, the installer will ask:
Do you wish to update your shell profile to automatically initialize conda?
We recommend you answer yes to this question. This will add the necessary lines to your shell profile to ensure that conda is added to your PATH variable and properly initialized when you open a new shell. Note: For changes to take effect, you will need to close and re-open your current shell.
Once the installation has completed, you can verify it was correctly installed by opening a new command line. You should see (base) next to your command line prompt. Additionally, the following command:
echo $CONDA_PREFIX
should return the path to your miniforge installation, by default this is ~/miniforge3 (i.e., miniforge3 in your home directory), so for example:
/Users/username/miniforge3
or
/home/username/miniforge3
If you did not have the installer initialize your shell, you can manually initialize it. Note: the command depends on installation location of miniforge, by default this is ~/miniforge3. Then, run:
~/miniforge3/condabin/conda init
Again, for changes to take effect, you will need to close and re-open your current shell.
cmd +
space)We will use a virtual environment to encapsulate the Python tools used for this workshop.
This ensures that the requirements for this workshop do not interfere with
any other Python projects. To create the environment (named
napari-workshop) with Python 3.11 in it, enter the following command:
conda create -n napari-workshop -c conda-forge python=3.12 napari pyqt jupyterlab
Once the environment setup has finished, activate the environment:
conda activate napari-workshop
If you successfully activated the environment, you should now see
(napari-workshop) to the left of your command prompt.
Remember to activate the right environment for what you need! And always
double-check that the activated environment is the one you want before installing any
packages—you never want to install into the `base` environment.
Test that your notebook installation is working. We will be using notebooks
for interactive analysis. Enter the command below and it should launch the
jupyter lab application in a web browser. Once you’ve confirmed it
launches, close the web browser and press ctrl+c in the terminal window to
stop the notebook server.
jupyter lab
Test your napari installation. Enter the command below and an empty napari viewer should open. You can close the window after it opens using the File menu. Please note that it takes a bit of extra time (as much as 60 s) to launch napari the first time, particularly if your computer has security and virus scan applications running.
napari
{admonition} Errors launching?
Contact the workshop instructors or you can reach out to the napari community on the [napari zulip chat](https://napari.zulipchat.com/#narrow/stream/212875-general)
This installation guide has been reproduced and edited from an introductory napari tutorial at the Jackson Laboratory.