Deploy on Hugging Face Spaces

You can deploy notebooks with Mercury on Hugging Face Spaces (HF Spaces). When deploying on HF there is no option to serve several notebooks. Only single app-notebook can be deployed on HF Spaces.

Create a new Space

Please create a new Space by filling the form at As app type please select the Gradio. There is no official integration (yet!) of Mercury on HF Spaces.

Create a new Hugging Face Space

The Space that I'm using in this tutorial is available at the address

Add requirements.txt

Please create (Add file -> Create a new file) or upload (Add file -> Upload file) a new file requirements.txt. Please add there all required packages. I will add there mljar-mercury package as a requirement.


Create file

You will need to add two files to run the Mercury. The first file is the file that will start the Mercury server.

import os
from dotenv import load_dotenv
from subprocess import Popen

my_env = os.environ.copy()
# Please set your username and your Space name
my_env["HF_SPACE"] = "embed/pplonski/deploy-mercury"

command = ["mercury", "run", f"{os.environ.get('PORT', 7860)}"] 
worker = Popen(command, env=my_env) 


Please remember to set the HF_SPACE variable. Please set with your username and Space name. Please do not remove the embed/ prefix. The username and Space name is in the URL and at the top of the Space website. Example: my_env["HF_SPACE"] = "embed/your-username/your-space".

The file can be added at HF Space website (Add file -> Create a new file) or uploaded (Add file -> Upload file). The Add file button is available at Files and versions tab.

Upload the notebook

Please upload the notebook with Mercury YAML configuration in the first RAM cell. It can be done with Add file -> Upload file. The file that I upload is called demo.ipynb and is simple notebook that display greetings.

Greetings Notebook with YAML config

Running the app

Please wait a while till the Space in built. After successfull build you should be able to click App on the top left corner. The application should be ready to use.

Interactive Notebook with Mercury on Hugging Face Space

The interesting thing is that you can run standalone web app from HF. Just need to define new URL with your username and space.

My space link is: based on my username (pplonski) and Space name (deploy-mercury) I construct the link: This link can be used for example for embedding notebooks on the website like below:

The code to create embedded notebook:

    style="border: 1px solid #aaa">