How to Install Jupyter Notebook on macOS

Jupyter Notebook is one of the fastest ways to experiment with Python code, share interactive documents, and prototype data workflows. macOS gives you several ways to install it, so you can choose the workflow that best fits your toolchain. This guide compares the most common options, highlights when to reach for each one, and walks through the exact commands to get everything running smoothly.

What was actually run for this page (2026-09-28, macOS 26.5, Apple Silicon): the global-pip attempt against Homebrew’s Python, the full venv route, and a read of the Homebrew formula’s metadata. The Conda and JupyterLab Desktop sections were not re-run for this update. The outputs quoted below are copied from that run.

Before you start

• Make sure you have a recent version of Python. The /usr/bin/python3 on a Mac belongs to Apple’s developer tools and is not current: on the machine used for this page it reports Python 3.9.6. Most people install a newer Python from python.org  or via Homebrew (brew install python). Homebrew’s python3 reported Python 3.13.1 on the same machine.
• Open the Terminal application. All commands below are intended to run there.
• If you already installed Jupyter through one method, uninstall it before trying another to avoid confusing PATH entries.

Why a global pip install jupyter fails on Homebrew Python

Many guides, including an earlier version of this one, start with:

python3 -m pip install jupyter

If python3 is a current Homebrew Python, that command does not install anything. We tested Homebrew’s Python 3.13.1. Older Homebrew Pythons, from before Homebrew adopted this marker, may not refuse. Here is what it printed on the test machine (output shortened):

$ /opt/homebrew/opt/python@3.13/bin/python3.13 -m pip install jupyter
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try brew install
    xyz, where xyz is the package you are trying to
    install.

    If you wish to install a Python library that isn't in Homebrew,
    use a virtual environment:

    python3 -m venv path/to/venv
    source path/to/venv/bin/activate
    python3 -m pip install xyz
    ...

The exit code was 1. This is PEP 668 : Homebrew marks its Python as managed by Homebrew, so pip refuses to write into it. The message offers a --break-system-packages flag. Do not use it for Jupyter. It turns off a guard that Homebrew put there deliberately, so your packages end up mixed with the Python packages Homebrew itself manages. And when Homebrew moves you to a new Python minor version, the packages stay behind in the old version’s site-packages and the new interpreter cannot see them. (We did not run an upgrade to demonstrate this. It follows from Python keeping one site-packages per minor version.)

Pick one of the routes below instead. For most people that means a venv. We only tested Homebrew’s Python here. We did not check whether a python.org install refuses in the same way.

Recommended: pip inside a virtual environment

Virtual environments isolate dependencies for each project and prevent package conflicts. They are lightweight, standard, and easy to automate. To install Jupyter inside a venv:

1. Create and activate a virtual environment.

   python3 -m venv ~/.venvs/jupyter
   source ~/.venvs/jupyter/bin/activate

2. Upgrade pip and install Jupyter.

   python -m pip install --upgrade pip
   python -m pip install jupyterlab notebook

3. Launch Notebook (the jupyter command resolves to the copy inside the virtual environment).

   jupyter notebook

   On the test machine a clean install into a fresh venv gave the following (the two not installed lines, for ipywidgets and qtconsole, are left out):

   $ jupyter --version
   IPython          : 9.17.1
   ipykernel        : 7.3.0
   jupyter_client   : 8.10.0
   jupyter_core     : 5.9.1
   jupyter_server   : 2.21.1
   jupyterlab       : 4.6.4
   nbclient         : 0.11.0
   nbconvert        : 7.17.1
   nbformat         : 5.11.1
   notebook         : 7.6.3
   traitlets        : 5.16.1

   ipykernel arrives as a dependency, so the environment gets its own python3 kernel without an extra install step.

4. When you are done, deactivate the environment with deactivate. Reactivate it any time you need Notebook again by running source ~/.venvs/jupyter/bin/activate.

💡 Your new Jupyter still lists kernels from earlier installs. On the test machine, the fresh venv’s jupyter kernelspec list showed 8 kernels: its own python3, plus 7 left in ~/Library/Jupyter/kernels by earlier installs. Those seven are user-level and visible to every Jupyter on the machine. We counted them but did not launch them. A kernelspec whose command is a generic python may end up on the current interpreter, but one that names an absolute path to another environment starts that environment. If you pick one of those, imports will not see the packages in this venv. Check with jupyter kernelspec list, then look at the argv in each kernel.json. ModuleNotFoundError in Jupyter reproduces exactly that failure and shows how to check which interpreter a kernel starts.

Install with Conda (Anaconda or Miniconda)

Conda bundles Python, package management, and environment isolation. It is ideal if you work with data science libraries that ship Conda packages or if you prefer graphical installers.

1. Install Miniconda  or the full Anaconda  distribution for macOS (Intel or Apple Silicon).

2. Open a new Terminal window so that the conda command is on your PATH.

3. Create an environment and add Jupyter:

   conda create --name notebooks python=3.11
   conda activate notebooks
   conda install jupyterlab notebook

4. Start Notebook with jupyter notebook. Because Conda environments are isolated, each environment can hold a different Python version or set of packages without clashing.

Install with Homebrew

Homebrew is the most popular package manager for macOS. Use it if you already rely on Brew to manage developer tools:

brew update
brew install jupyterlab

Homebrew installs the jupyter command to /opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel).

What the formula pulls in matters more than where it lands. Its metadata on 2026-09-28 (brew info --json=v2 jupyterlab; we read it, we did not install it):

formula jupyterlab 4.6.4 | deps: certifi, cffi, libyaml, node, pandoc, python@3.14, rpds-py, zeromq

So Homebrew’s JupyterLab runs on its own python@3.14, which is not necessarily the python3 you use in the terminal. Its bundled kernel most likely runs that Python too, but we did not install the formula to confirm it. Either way, a package you pip install into a project venv is not visible to it until you register that venv as a kernel. From inside the venv, run python -m pip install ipykernel if it is not already there, then python -m ipykernel install --user --name myproject.

The formula also depends on pandoc, which is one of the pieces PDF export needs. We have not checked whether the formula also includes the notebook interface, so to use jupyter notebook rather than JupyterLab, the venv route is the one verified above.

⚠️ Homebrew installs Jupyter system-wide. If you need multiple versions of Python or isolated dependencies, pair Brew with virtual environments or Conda instead.

JupyterLab Desktop for macOS

Project Jupyter maintains a desktop application that bundles JupyterLab with its own Python runtime. Download it from the JupyterLab Desktop release page  and drag the app into your Applications folder. After launching the app you can open or create notebooks without touching the command line. It still respects Conda environments or virtual environments if you connect them via the kernel selector.

This option is perfect for new users who prefer a GUI or teams that need a self-contained installation.

Choosing the right path

Whatever you choose, keep your environments tidy by periodically removing unused packages and pinning versions in a requirements.txt or environment.yml. Jupyter Notebook will feel right at home on your Mac once you do.

Next steps

• If you only need to open or share one notebook, you may not need Jupyter at all. To turn an .ipynb someone sent you into something readable, the Runcell Jupyter to PDF converter  and ipynb to HTML converter  work in the browser, with no Python, TeX or pandoc on the Mac.

• Exporting notebooks: Jupyter nbconvert: Convert Notebooks to HTML, PDF & Python covers every output format.

• When export fails: PDF export in particular has a long dependency chain — pandoc, a TeX distribution, and a package set that surfaces one missing file at a time. nbconvert PDF Export Errors is a lookup table of the common error messages with their actual causes. The venv route above already pulls in ipykernel as a JupyterLab dependency, so --execute works; a bare pip install nbconvert environment does not, and raises NoSuchKernel: No such kernel named python3.

• When the notebook cannot find your packages: picking two different rows of the table above — say Homebrew for Jupyter and venv for your project — is the single most common way to end up with ModuleNotFoundError in a cell for a package that imports fine in the terminal. ModuleNotFoundError in Jupyter: A Reproduced Kernel Failure Matrix shows which interpreter each kernel actually starts, and why activating the venv often changes nothing.

• When export succeeds but the PDF is wrong: Jupyter to PDF: A Measured Fidelity Benchmark converts nine probe notebooks through all three export paths and counts what actually survives into each PDF.

• Keeping the repo clean: What is .ipynb_checkpoints? explains the folder Jupyter creates alongside your notebooks, and why adding it to .gitignore does not untrack the copies you already committed.