API Docs
How does it work?

How does Mercury work?

Mercury is an open-source framework for converting Python notebooks into web applications.

It consists of two parts:

  • Mercury Widgets - set of Input Widgets and Output Widgets. User can interact with notebook thanks them.
  • Mercury Server - serves notebooks as web applications. It can serve multiple notebooks to multiple users.

Mercury Apps

Mercury Apps are developed in two steps.

Notebook development

You need to create a Python notebook in Jupyter Notebook. During development you can use Mercury Widgets. You can interact with them, but only widget value will be updated. You need to manually run cells below the widget code to see change.

Mercury App

Input widgets are displayed in the sidebar. Any widget change triggers automatic cells re-execution. Only cells below widget definition code are re-executed.

You can hide notebook's code, add authentication, produce file for download and many more ...

Mercury Widgets

Mercury Widgets are created based on ipywidgets (opens in a new tab) package. The main difference is automatic re-execution of cells after widget update when notebook is served as Mercury App. There is no automatic re-execution when developing notebook in the Jupyter Notebook, after widget change you need to manually execute cells below the widget.

Mercury Server

Mercury Server is created based on Django (opens in a new tab), Django Channels (opens in a new tab) and React (opens in a new tab). It reads your notebooks and serves them as web applications. When a user opens a notebook in the web browser, a WebSocket connection between the browser and Mercury Server is established. Mercury Server ensures that there is worker available. Worker is connected to Mercury Server with WebSocket. Mercury Server is a proxy between web browser and worker. Every action from user is forwarded by Mercury Server to the worker. Worker responses are sent to the client browser passing through Mercury Server.

Worker keeps open IPython kernel and knows the code from the notebook. User widgets interactions are executed by the kernel. Results are send as notebook output.

Mercury vs Voila

Voila (opens in a new tab) is similar framework to Mercury. They both serve notebooks as interactive web apps.

The main differences:

  • Mercury offers simple re-execution of cells after widget update.
  • Mercury display all input widgets in the sidebar - you have app with ready layout.
  • Mercury provides OutputDir for downloading files created in the notebook.
  • You can create interactive presentations with Mercury.
  • Mercury has built-in authentication (coming soon).
  • Mercury provides easy PDF/HTML notebook export.
  • Mercury Cloud (coming soon) offers super easy deployemnt - just upload your notebook.
  • You can schedule automatic execution of the notebook (coming soon). It is useful for building automatic reporting systems or dashboards with auto-refresh.

Mercury vs Streamlit

Streamlit (opens in a new tab) is a Python framework for creating web apps.

The main differences:

  • Mercury works with Jupyter Notebooks, Streamlit works with Python scripts. With Mercury you don't need to rewrite your analysis from Jupyter Notebook to Python script.
  • Mercury provides OutputDir for downloading files created in the notebook.
  • You can create interactive presentations with Mercury.
  • Mercury has built-in authentication (coming soon).
  • Mercury provides easy PDF/HTML notebook export.
  • You can schedule automatic execution of the notebook (coming soon).