jupyter/jupyter: The Metapackage That Installs the Whole Jupyter Stack

What the jupyter Repository Actually Contains

The name is misleading in a useful way. The repository at jupyter/jupyter does not contain the notebook server, the kernel protocol, or the Lab front end. Its setup.py declares a package named jupyter with an empty py_modules list, which means the distribution installs no importable module of its own. What it does carry is a dependency list. The description in setup.py states the intent plainly: "Jupyter metapackage. Install all the Jupyter components in one go." The install_requires entry names five packages: notebook, nbconvert, ipykernel, ipywidgets and jupyterlab.

The second job of the repository is documentation. The README describes the docs as living in docs/source, written in a mix of reStructuredText and MyST Markdown, and built with Sphinx into docs/build. The README also lists translations of itself in Spanish, Portuguese and French. So the audience splits in two: Python users who want the standard stack installed without naming five packages, and contributors who want to build the ecosystem documentation locally.

If you arrived looking for the notebook application itself, you are in the wrong repository. Installing this metapackage gets you the notebook application as a side effect, but the code you would file a bug against lives elsewhere.

How a Metapackage Resolves Into a Working Notebook Server

There is no runtime machinery here. When pip processes this distribution it reads install_requires and adds notebook, nbconvert, ipykernel, ipywidgets and jupyterlab to the resolution set, then installs whatever versions satisfy every constraint across the whole environment. The metapackage contributes no files to site-packages beyond its metadata.

The consequence is that the versions you end up with are decided by pip's resolver at install time, not by this repository. The setup.py pins nothing. There is no upper bound on notebook or jupyterlab, and no lock file in the top-level entries. Two machines installing the same jupyter version on different days can receive different component versions.

The components themselves are not interchangeable. ipykernel provides the kernel that executes your code and talks the Jupyter messaging protocol. notebook and jupyterlab are two different front ends over that protocol, and installing both is deliberate: the metapackage gives you the classic notebook interface and Lab. nbconvert turns notebooks into other formats, and ipywidgets supplies interactive widgets for the front ends. The README does not explain this split, so a new user reading only this repository has no way to learn which component does what. That is a documentation gap, not a design flaw, but it is the gap most likely to confuse someone who installs the metapackage and then wonders why two browser interfaces appeared.

Installing the jupyter Metapackage and Starting a First Notebook

The README documents how to build the documentation, not how to install the package for use. Installation follows from the packaging metadata: the distribution is named jupyter and is published to PyPI by GitHub Actions on release, as the README's release section describes. A standard pip install is therefore the entry point.

pip install jupyter

This resolves the five declared dependencies. Because setup.py sets python_requires to >=3.6 and lists classifiers from Python 3.6 through 3.13, the install is expected to work on those interpreters. On an unsupported interpreter pip will refuse rather than install and fail later.

Once installed, the notebook server is started from the command line. The README does not show this command, but it is the interface the notebook package provides.

jupyter notebook

The server prints a URL with a token and opens a browser tab. A new notebook created there runs against ipykernel. If you prefer the Lab interface, the jupyterlab dependency is already present, so the same environment serves it.

jupyter lab

To confirm what the metapackage actually brought in, inspect the installed distributions rather than the metapackage itself.

pip show jupyter

The output lists the five requirements. If you want the documentation locally instead, the README's nox route clones the repository, installs nox with pip, and runs a single session.

nox -s docs

The README states this installs dependencies into a virtual environment and writes HTML into docs/build/html. A second session, nox -s docs-live, rebuilds on file changes and serves a live preview.

Where the Metapackage Model Breaks Down

The main limitation is version control. Because nothing is pinned, this package cannot give you a reproducible environment on its own. If your work depends on a specific notebook or jupyterlab release, installing jupyter and hoping is the wrong approach; you want the individual packages pinned in a requirements file or a lock file, and you may not need the metapackage at all.

The second limitation is weight. A server deployment that only needs to execute notebooks headlessly does not need jupyterlab or ipywidgets. Installing the metapackage puts both front ends and the widget stack into the image, along with nbconvert. For a container that runs papermill-style batch execution, that is dead weight and extra surface to patch. The README says nothing about a minimal install path, because the package has no configuration options to offer one.

The third limitation is scope confusion. The repository is also the documentation home, so issues and pull requests about the docs and issues about dependency resolution land in the same place. The README's release section notes that releases "happen very rarely" and are made with tbump by anyone with push access, which tells you the maintainers treat this as a low-churn package. That is appropriate for a dependency list, but it means you should not expect the metapackage to move quickly when a component has a problem.

Finally, the README does not document rollback or downgrade behaviour. If a fresh install pulls a component version that breaks your workflow, the recovery path is pip's, not this project's.

jupyter Versus Installing notebook or jupyterlab Directly

The real alternative is to skip the metapackage and install the components you actually use. If you only want the classic notebook interface, pip install notebook gives you the server and pulls ipykernel as its own dependency, without jupyterlab or ipywidgets. If you only want the newer interface, pip install jupyterlab does the same in the other direction. The difference in approach is control: direct installation lets you pin each package, hold jupyterlab back a major version, or drop nbconvert from a runtime image entirely.

The trade-off runs the other way too. The metapackage exists because the common case is a user who wants the standard set and does not want to reason about which five packages constitute it. For a teaching environment, a laptop, or a first install, naming one package is less error-prone than naming five and forgetting ipykernel. The metapackage also acts as a compatibility statement: the Jupyter Development Team is asserting that these five packages, at whatever versions resolve together, form a coherent installation.

A narrower alternative for the documentation half of the repository is to read the published docs at the homepage rather than building them. The nox route is for people editing docs/source, not for people who want to read them.

Maintenance, Releases and the BSD-3-Clause Licence

The repository is not archived, and its last push was on 2026-07-09. Releases, per the README, are made with tbump, which updates version numbers and publishes a git tag; GitHub Actions then builds the release and publishes it to PyPI. The README states this "happens very rarely." The setup.py version currently reads 1.2.0.dev0, so the development line is at 1.2.0.

The upgrade cost is low by construction. There is no code to migrate, no API to relearn, no configuration schema. Upgrading the metapackage changes which component versions pip is willing to resolve, and the risk lives entirely in those components. The practical upgrade check is to diff the installed component versions before and after.

The licence is BSD-3-Clause, matching the BSD identifier in setup.py and the LICENSE file at the top level. For a metapackage this matters less than usual, because you are not redistributing this project's code; you are redistributing its dependency list. The licences that bind your distribution are those of notebook, nbconvert, ipykernel, ipywidgets and jupyterlab. Check each of those for your own redistribution case. Nothing here is legal advice.

The security policy lives in SECURITY.md at the repository root, which is where the project directs vulnerability reports.

Who Should Install jupyter and Who Should Not

Install it if you are setting up a workstation or a teaching image and want the standard Jupyter components present without tracking five package names. Install it if you are contributing to the ecosystem documentation and want the nox sessions the README describes. Install it if you are on a CPython version between 3.6 and 3.13 and want pip to decide the component versions for you.

Do not install it for a production service that needs pinned versions, and do not install it into a slim container that only executes notebooks. In both cases the individual packages give you a smaller, more predictable result. Do not install it expecting to find the notebook source code; the repository has none.

Before you commit to it, check two things. First, read install_requires in setup.py to confirm the component list still matches what you expect, since that list is the whole package. Second, decide whether you are willing to accept unpinned component versions; if not, the metapackage is the wrong tool and a pinned requirements file naming notebook or jupyterlab directly is the right one.

Editorial conclusion

Adopt jupyter/jupyter when you want one pip install to bring in the standard Jupyter components on a supported CPython version, and when you are content to let pip resolve the individual package versions. Do not adopt it if you need pinned component versions, a minimal install, or a package that ships its own code. Before installing, check the current contents of install_requires in setup.py, because that list is the entire contract of the package.

Frequently asked questions

Official sources

1. Issues
2. jupyter/jupyter on GitHub
3. License: BSD-3-Clause
4. Project website
5. README