Python

Written & tested for accuracy by a developer (not AI)

Install Jupyter on Mac

Install Jupyter Notebook on Mac. How to install JupyterLab with uv and use your project's Python packages in a Jupyter notebook. A free app to install Jupyter.

Use Jupyter when you want to run Python code interactively, a few lines at a time, and see output, such as a table or a chart, along with the code. Jupyter is a free, open-source program that opens a "notebook" in your web browser. A notebook is a page that mixes code, its output, and your own notes. Scientists, data analysts, teachers, and students use notebooks to explore data, teach, and try out ideas while writing Python code.

Jupyter has a reputation as difficult to use, especially for beginners. Setting up Python environments and installing new packages can be quite cumbersome, and gets even more complicated when people install Jupyter with Anaconda, a huge download that brings its own copy of Python, or with a pip install command from a tutorial.

Many experienced Python developers now prefer to install Jupyter with uv, a fast tool that installs Python and Python packages. I've built a free app that installs uv and Python. It also sets up Jupyter inside a project, so a notebook runs the same Python and the same packages as the project's code, which prevents many errors.

Installing Python tools is one step in setting up your Mac. See the Mac development setup guide.

Before you get started

I recommend using our free app to set up Jupyter on your Mac. It is a FREE Mac app that installs uv and Python, sets the PATH so the python command works, and verifies Python is working. As an optional step, it creates a project folder for Jupyter notebooks, with JupyterLab, NumPy (for working with numbers), and Matplotlib (for drawing charts) ready to use. Using the app is easier and faster than following this guide. Here are all the details about the app before you download. Then download it:

JupyterLab or Jupyter Notebook

Jupyter comes in two versions that open the same notebook files (files ending in .ipynb). JupyterLab is a full editor, with a file browser, tabs, and a terminal. Jupyter Notebook is the simpler, classic view, with one notebook in each browser tab. I recommend JupyterLab because it has more features. The instructions here install it.

Install and use Jupyter from my app

The easiest way to get Jupyter going is to use my free app, "Set Up Your Mac for Python". It sets up uv and Python, and offers an optional Jupyter-Notebooks folder in your Documents folder. The folder is a uv project with a starter notebook to try.

After you set up Jupyter with my app, open a terminal application, move into the Jupyter notebooks folder, and launch JupyterLab with uv run:

$ cd ~/Documents/Jupyter-Notebooks
$ uv run jupyter lab

Be sure to type uv run jupyter lab, not just jupyter lab. The jupyter command is inside the project, where the shell can't find it on its own, so plain jupyter lab gives the error zsh: command not found: jupyter.

When JupyterLab opens in your web browser, double-click the starter notebook in the file browser on the left to open it. To make a new notebook, click "Jupyter-Notebooks" under "Notebook" in the Launcher. New notebooks are saved in the Jupyter-Notebooks folder.

To add a package, run uv add in the folder. For example, you might want to add pandas, a package for working with tables of data:

$ uv add pandas

Keep all your notebooks in this folder, with the packages you need most often. Notebooks you bring over from an old Anaconda setup can go here too. If one of them can't find a package, see "Fix ModuleNotFoundError in a notebook" below. To make a second project, see "Notebooks in a new project" below. To stop JupyterLab, press Control + C twice in the terminal window where it is running.

How to install Jupyter on your own

Here's how to install Jupyter if you don't want to use my app and prefer to do each step yourself. First, check the macOS version. If you're running an older version, update macOS to the latest macOS version.

Jupyter needs the Python language. I recommend using uv to install both Python and Jupyter. Astral's uv is a fast tool that installs Python, creates a separate environment for each project, and adds packages to it. Open a terminal application and check if uv is installed:

$ uv --version
uv 0.13.0

If it is installed, you'll see a version number. If you see zsh: command not found: uv instead, install uv first. I recommend installing uv with Homebrew, the free package manager many developers use to install their tools:

$ brew install uv

If you don't have Homebrew, or prefer Astral's own installer, see the article Install uv on Mac. Then run uv --version again to check that uv is installed.

You don't need to install Python after installing uv, because uv downloads Python when a project needs it.

Setting up a Jupyter project

To get started using Jupyter, make a new project with uv and move into its folder. The example is named my-notebooks.

$ uv init my-notebooks
$ cd my-notebooks

The uv init command creates the folder, with a pyproject.toml file that lists the packages the project uses (see the article What Is pyproject.toml?). Add the packages you want in your notebooks. For example, many people want pandas, a package for working with tables of data:

$ uv add pandas

Then add JupyterLab to the project:

$ uv add --dev jupyterlab

The --dev option marks JupyterLab as a tool for working on the project, separate from the packages the project's code needs to run.

Start JupyterLab with uv run:

$ uv run jupyter lab

JupyterLab opens in your web browser, usually at localhost:8888/lab. If another JupyterLab is already running, the new one uses the next port, such as 8889. In the Jupyter Launcher, click "Python 3 (ipykernel)" under "Notebook" to create a notebook. Type a line of code in the first cell and press Shift + Return to run it:

import pandas
pandas.__version__

The version of pandas appears below the cell. The notebook runs the project's own Python, from the project's hidden .venv folder, so it finds every package you add with uv add. To add a package while you work, run uv add in a notebook cell. Start the line with !, which tells Jupyter to run it as a terminal command:

!uv add matplotlib

The package is added to the project's pyproject.toml file. You can import it in the next cell. You can also run uv add in a second terminal window in the project folder. If an import still fails afterwards, choose Kernel > Restart Kernel.

Many tutorials say to run %pip install or !pip install in a cell. In a uv project, %pip install fails with "No module named pip", because uv doesn't put pip in a project's environment. The !pip install line runs whichever pip your terminal finds first, so the package may go into a Python the notebook doesn't use. Use !uv add instead.

To stop JupyterLab, go back to the terminal window where it is running and press Control + C twice. The next time you want to work in the project, cd into its folder and run uv run jupyter lab again.

Notebooks in a new project

Each project keeps its own list of packages. If you make a second project for notebooks, add JupyterLab and the packages it needs with uv add, as you did in the first one. You can name several packages in one uv add command.

You'll be relieved to learn that the packages aren't downloaded twice. The uv tool keeps a single copy of every package it downloads, in a cache folder in your home directory. On a Mac, it gives each project a copy-on-write clone of it, which shares the same space on the disk until one of them changes. On my Mac, a second project with NumPy, SciPy, and Matplotlib only needed about 2 MB of extra disk space (the du command reports 150 MB, because it can't see the shared space).

You don't need a new project for every notebook. If you are using notebooks only for your own work, keep them all in one project, with the packages you use most. Make a new project when a piece of work needs different packages or versions, or you intend to share the project with other people.

Optional JupyterLab for every project

If you'd rather have one JupyterLab that opens anywhere on your Mac, install it as a uv tool. A tool is a program that uv installs once, in an environment of its own, and puts its commands in a folder on your PATH:

$ uv tool install jupyterlab --with-executables-from jupyter-core

Include the --with-executables-from jupyter-core option. Without it, uv installs only JupyterLab's own commands, such as jupyter-lab. Typing jupyter lab then gives the error zsh: command not found: jupyter. To get the classic Jupyter Notebook as well, use --with-executables-from jupyter-core,notebook.

Then start JupyterLab from any folder:

$ jupyter lab

This JupyterLab has its own Python, separate from your projects, so its notebooks can't import a project's packages. To use a project's packages, register the project as a kernel, the Python that runs a notebook's code. In the project folder, add the ipykernel package and register the project:

$ uv add --dev ipykernel
$ uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=my-notebooks

Replace my-notebooks with the name of your project. The command saves the kernel's settings in ~/Library/Jupyter/kernels in your home directory. In JupyterLab, the project's name now appears in the Launcher beside "Python 3 (ipykernel)". Choose it for a new notebook, or switch an open notebook to it with Kernel > Change Kernel.

Fix ModuleNotFoundError in a notebook

A notebook that can't find a package shows an error such as this one:

ModuleNotFoundError: No module named 'pandas'

There are two causes. Either the package was never added to the project, or it went into one Python while the notebook's kernel is running another.

The first cause is common when you open notebooks from an old Anaconda setup. Anaconda installs hundreds of packages, such as NumPy, SciPy, and Matplotlib, so its notebooks import them without any setup. A new uv project starts with none. Add the packages your notebooks import, in the project folder:

$ uv add numpy scipy matplotlib

The second cause, the wrong Python, is the problem beginners ask about most often in Jupyter forums. It happens when you install a package with pip or Homebrew in a terminal, or when a JupyterLab installed as a uv tool opens a notebook in a project folder. Run this in a notebook cell to see which Python the kernel uses:

import sys
sys.executable

If the path ends in your project's .venv/bin/python, add the package with !uv add in a cell, or with uv add in the project folder. If the path is anything else, the notebook isn't using the project. Start JupyterLab with uv run jupyter lab in the project folder, or choose the project's kernel, as described above.

If you started JupyterLab with uv run jupyter lab and the path still isn't your project's, an old kernel is taking the project's place. Older tutorials register a kernel named python3 in ~/Library/Jupyter/kernels, and Jupyter looks there before it looks in the project. Remove the old kernel's settings, then restart JupyterLab:

$ uv run jupyter kernelspec remove python3

The command asks you to confirm, and deletes only the kernel's settings, not the Python it used. Your project's own kernel takes its place.

Ways to install Jupyter I don't recommend

You'll see other ways to install Jupyter in tutorials. Here's why I recommend the uv method:

  • pip install jupyterlab - Jupyter's own site gives this command, but on a Mac it fails with error: externally-managed-environment when the Python comes from Homebrew or uv. Both mark their Python as managed by them, so pip won't add packages to it.
  • brew install jupyterlab - this works, but it installs Homebrew's own Python version to run JupyterLab, a second Python beside the one uv manages. Its notebooks don't see a uv project's packages unless you register the project as a kernel.
  • Anaconda - Anaconda is a large download that bundles Python, Jupyter, and hundreds of packages for data science. Scientists and students often use it because one install gives them a ready-made setup. It installs its own Python and its own jupyter command, and puts them first on your PATH. That makes it hard to tell which Python a notebook or a terminal is using. Anaconda is free for personal use, but larger companies need a paid plan. Use uv unless everyone in your workplace prefers Anaconda.
  • JupyterLab Desktop - a stand-alone app that bundles its own Python, maintained by a small group of contributors. Some teachers suggest it because it needs no command line. However, its setup on macOS can be problematic.

Jupyter in VS Code

You can also open notebooks in VS Code, with Microsoft's Python and Jupyter extensions. VS Code needs only the ipykernel package in the project:

$ uv add --dev ipykernel

Open the project folder in VS Code and create a notebook with the command "Create: New Jupyter Notebook". Click "Select Kernel" and choose the Python in the project's .venv folder.

Now you can install Jupyter, open a notebook in a project of your own, and use any package you add with uv add. When a notebook can't find a package, you know how to check which Python it uses and fix it.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.