Open-source project
mljar/mercury avatar
mljar/mercury

Mercury turns a notebook into a web app by rerunning cells

Impress your boss and turn a Jupyter notebook into a beautiful, shareable web app — no callbacks, no frontend, no rewrite.

4,359 stars292 forksPythonApache-2.0

At a glance

What is it?
Mercury serves Jupyter notebooks as standalone web apps through reactive reruns rather than callbacks, which suits analysts who already have working notebook code and want to share it without writing frontend.
Who is it for?
Analysts with a finished notebook and a read-mostly audience should try Mercury, because turning existing cells into an app costs one pip install and one command. Teams that need real request handling, per-user state or a public login flow should not, since authentication beyond a single shared password is a paid option and every widget interaction re-executes cells.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 20 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • mljar/mercury4,359 ★ · +6
Star history
Repository2026-09-232026-11-15
mljar/mercury4.4k4.4k

6 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Widget changes re-execute the notebook instead of calling a function

The whole design rests on one decision: there are no callbacks. When a visitor moves a widget in the browser, Mercury does not dispatch an event handler into your Python code. It re-executes cells, and the widget object reads the new value during that pass. The README puts it plainly: "Widget interactions fire cells re-execution".

That choice buys you something a normal notebook cannot give you. Code that reads the widget object gets the new number on the next run, and code below it recomputes. Dash works the other way around: a callback fires, updates a component, and nothing else in the page re-executes unless you wrote that too.

The price follows from that: every widget interaction triggers cell re-execution. If your notebook trains a model in cell four, a visitor who touches a slider in cell one pays for cell four too. For a report whose cells are milliseconds each, that is invisible. For a notebook that loads a large CSV on every pass, it is the whole cost model.

The mercury command serves every notebook in a directory

Installation is a single PyPI package, and the server is its console entry point. `pyproject.toml` maps the script `mercury` to `mercury_app.__main__:main` and pins `requires-python = ">=3.10"`, and depends on `jupyterlab>=4.6.4,<5`.

bash
pip install mercury

Run it from the folder holding your notebooks and every notebook there becomes a web app:

bash
mercury

Without arguments it detects notebooks in the current directory. To point it elsewhere, and to make relative paths resolve against that same place, pass `--working-dir`:

bash
mercury --working-dir /path/to/notebooks

You can pair the directory with a single notebook file, which is what you want when a directory holds scratch work you do not intend to publish:

bash
mercury app.ipynb --working-dir /path/to/notebooks

The working directory matters more than it looks. `--working-dir` is the base for notebooks, for `config.toml`, and for relative file access, so a data file read with a relative path resolves against it. Moving the server's base moves what your code can open.

Widget values are read from objects created at cell time

A Mercury app is ordinary Python. The echo chat example in the README is a cell-by-cell transcript of what the widget model requires.

python
# import package
import mercury as mr
python
# create Chat widget
chat = mr.Chat()
python
# create chat prompt
prompt = mr.ChatInput()
python
if prompt.value:
    # user message
    user_msg = mr.Message(prompt.value, role="user")
    chat.add(user_msg)

`prompt.value` is only populated after a run triggered by the user's submission, so the guard on `if prompt.value` is what keeps the rest of the cell from firing on the initial load. Read that pattern as the template for any conditional UI: check the widget, act inside the guard.

The package depends on `anywidget>=0.9.0`, which is how custom widgets would reach the browser, and the chat component is only one of the widget set the README points to RunMercury.com/examples for. Predefined layout is the other half of the pitch: the README says you don't need to worry about UI because the layout is predefined.

config.toml sits in the working directory, not in the repo root

Appearance is set by a TOML file, and where it lives trips people up. Mercury looks for `config.toml` in the active notebooks directory, which is the current directory unless you started the server with `--working-dir`. If you used that flag, the file goes there. The repository ships `example.config.toml` as the template.

toml
[main]
title = "Mercury"
footer = "MLJAR - next generation of AI tools"
favicon_emoji = "🎉"
notebooks_button_label = "Notebooks"
starting_message = "Initializing web application…"
starting_icon = "spinner"
show_search_filter = true

Keys under `[main]` act as defaults for the whole notebooks directory, while notebook metadata can still override the thumbnail per notebook. `starting_icon` takes `coffee`, `spinner`, or `none`, which is a short closed list and the only enumerated value in the file.

Per-notebook appearance is set in the app preview toolbar rather than in this file: notebook title, description, icon emoji, icon colour, whether the code is displayed, and whether the app goes full width. The home page is therefore configured in two places at once, and a reader looking for why a thumbnail is wrong has to check both `config.toml` and the notebook metadata.

Default sessions are per viewer; --keep-session merges them

By default each viewer gets independent widget values and kernel state. Two people open the same app, drag the same slider to different values, and neither sees the other's numbers. For a dashboard that is the correct behaviour.

`--keep-session` inverts it. Every viewer shares one live Python session, widget changes and outputs synchronise across connected browsers, and what one person does to a widget appears in everyone else's page. The README also states that reruns are serialised and changes arriving during a busy rerun are coalesced, so the shared session still executes one rerun at a time. That is the sensible reading of a single shared kernel: the mode is for a room watching one analysis together, not for two operators.

The other server-level flags are few. `--log-level=INFO` or `--log-level=DEBUG` raises logging from its `CRITICAL` default. `--timeout=600` bounds resource use in seconds, and the README's advice is to be generous. `--pass=your-secret-here` puts one password in front of every notebook.

bash
mercury --pass=your-secret-here

One password is the entire authentication story in the open source build. User-based authentication is described as a paid option handled by contacting mljar.com, so anything needing per-user accounts or distinct permissions is outside what this package gives you.

The JupyterLab preview extension stops at Google Colab and VS Code

The live app preview is a JupyterLab extension, and the README is blunt about where it does not work: "It will not work in Google Colab and VS Code - sorry guys!". The extension is also tied to MLJAR Studio. Its build is driven by `hatch-nodejs-version` and `hatch-jupyter-builder`, and `package.json` pins resolutions for the Microsoft fast-element and fast-foundation packages the frontend uses, so the extension is versioned against JupyterLab 4 rather than installed as an independent piece of UI.

The gap matters for anyone whose notebook habit lives in Colab or in VS Code's notebook interface. There, the framework still serves your notebook, but the loop of "edit cell, click the preview icon, see the app" is gone. You are left editing blind and reloading the served page to check your work, which is a materially slower way to build a UI.

A second limit sits next to it. Docker deployment is a short image that installs from PyPI and exposes a port:

dockerfile
FROM python:3.12-slim

RUN pip install mercury

WORKDIR /workspace

EXPOSE 8888

CMD ["mercury", "--ip=0.0.0.0", "--no-browser", "--allow-root"]

`--allow-root` is there because containers run as root, and `--no-browser` stops the server trying to open one. Anyone exposing this needs to know that a single shared password plus a notebook directory is the whole access model.

Where Mercury differs from Dash and Streamlit

Dash and Streamlit both rebuild the execution model instead of inheriting the notebook one. In Streamlit your script reruns top to bottom on every interaction too, which sounds identical until you notice the pieces: widget state lives in the session, layout is declared with layout primitives, and expensive calls can sit under a caching decorator.

The practical difference is where state goes. Streamlit gives you a session object that outlives a rerun, so a chat history can accumulate in it. Dash sits furthest away, running callbacks inside one long-lived Flask process, so no rerun of unrelated cells is required at all.

Mercury's case is that this distance is worth zero. If your analysis already exists as a notebook, there is no translation step, no component wrapper, and no second copy of the logic in a callback function. Choose it when the notebook is the artefact you already maintain. Choose Streamlit or Dash when the notebook is scaffolding you intend to delete.

Two facts a skim misses: --working-dir moves config.toml, and the Run button changes execution

Two details punish a skim. First, `config.toml` and notebook discovery are both anchored to the working directory, and the Dockerfile makes that concrete: it sets `WORKDIR /workspace` and expects notebooks to be mounted there. Start the container with notebooks mounted somewhere else and forget `--working-dir`, and you get an empty home page plus a missing config file, in that order.

Second, the execution model is not fixed. Unchecking auto re-run in the app preview toolbar removes the per-widget rerun and adds a Run button in the sidebar, which then executes cells top to bottom on click. That single switch converts Mercury from a reactive app into a batch job with a front end, and it is the setting to reach for when the eager response on every keystroke-level widget change is costing more than it returns.

The project is under Apache-2.0, and the last push on the repository was on 2026-10-26, with v3.2.13 tagged on 2026-10-26 after v3.2.12 on 2026-10-24 and v3.2.11 on 2026-09-10.

Editorial conclusion

Analysts with a finished notebook and a read-mostly audience should try Mercury, because turning existing cells into an app costs one pip install and one command. Teams that need real request handling, per-user state or a public login flow should not, since authentication beyond a single shared password is a paid option and every widget interaction re-executes cells. Before adopting it, open one of your heavier notebooks and time a single rerun, because the entire interaction model rests on that number.

Frequently asked questions

What is Mercury the Python framework?

Mercury is a Python framework for building interactive web applications directly from Jupyter notebooks, including chats, AI agents, dashboards and reports. It ships a set of widgets, a standalone server that serves notebooks as web apps, and a JupyterLab extension for live app preview.

How do I install Mercury and start the server?

Install the package with `pip install mercury` and start the server by running `mercury` in the folder holding your notebooks. By default it detects all notebooks in the current directory and serves them as web apps.

Does the Mercury app live preview work in Google Colab or VS Code?

No. The live app preview extension is available only for JupyterLab and MLJAR Studio, and the README states it will not work in Google Colab or VS Code.

Can Mercury serve multiple notebooks from another directory?

Yes. Pass `mercury --working-dir /path/to/notebooks` to serve notebooks from a different directory and make relative paths, `config.toml` and relative file access resolve from there. You can combine it with a notebook argument such as `mercury app.ipynb --working-dir /path/to/notebooks`.

Does Mercury support user accounts and login?

The open source build offers a single server password set with `mercury --pass=your-secret-here`. User-based authentication is a paid option, with details available by contacting mljar.com.

What licence is Mercury released under?

Mercury is released under the Apache-2.0 licence. The repository lists the licence as a file in pyproject.toml and ships a LICENSE file at the top level.

Official sources

  1. License: Apache-2.0
  2. mljar/mercury on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/mljar-mercury.svg)](https://hysenlabs.com/projects/mljar-mercury)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/mljar-mercury.svg)](https://hysenlabs.com/projects/mljar-mercury)

Was this useful?