Skip to content

Installation

Requirements

  • Python 3.10+
  • marimo >= 0.19.8
  • jupyter-server-proxy (installed automatically)

Basic Installation

marimo-jupyter-extension requires marimo but does not declare it as a dependency, allowing flexible installation scenarios.

pip install 'marimo>=0.19.8' marimo-jupyter-extension

Or with uv:

uv add marimo marimo-jupyter-extension

Single Python Environment

The simplest setup has both packages in the same environment:

FROM quay.io/jupyterhub/jupyterhub:latest
RUN cd /srv/jupyterhub && jupyterhub --generate-config && \
    echo "c.JupyterHub.authenticator_class = 'dummy'" >> jupyterhub_config.py && \
    echo "c.DummyAuthenticator.password = 'demo'" >> jupyterhub_config.py && \
    pip install --no-cache-dir notebook 'marimo>=0.19.8' marimo-jupyter-extension
RUN useradd -ms /bin/bash demo

Multiple Python Environments

With more complex setups (conda, virtualenvs), install packages in the correct environments:

Package Install Location Why
marimo User's environment Access user's packages
marimo-jupyter-extension Jupyter's environment Jupyter must import it

Example with Miniforge:

FROM quay.io/jupyterhub/jupyterhub:latest

RUN cd /srv/jupyterhub && jupyterhub --generate-config && \
    echo "c.JupyterHub.authenticator_class = 'dummy'" >> jupyterhub_config.py && \
    echo "c.DummyAuthenticator.password = 'demo'" >> jupyterhub_config.py && \
    pip install --no-cache-dir notebook

ENV PATH=/opt/conda/bin:$PATH
RUN curl -fsSL https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh -o /root/miniforge.sh && \
    bash /root/miniforge.sh -b -p /opt/conda && rm /root/miniforge.sh

# marimo in conda environment (user packages available)
RUN /opt/conda/bin/pip install --no-cache-dir 'marimo>=0.19.8'

# marimo-jupyter-extension in Jupyter's environment
RUN /usr/bin/pip install --no-cache-dir marimo-jupyter-extension

RUN useradd -ms /bin/bash demo

DockerSpawner

For JupyterHub with DockerSpawner, install both packages in the single-user container images. They are not needed in the hub container.

Verifying Installation

After installation, start JupyterLab:

jupyter lab

You should see a marimo icon in the launcher. If not, see Troubleshooting.