Publish marimo notebooks to GitHub Pages

Publishing your marimo notebooks has never been easier. In this guide, we’ll show you how to convert your interactive Python notebooks into self-contained WASM-powered HTML files and then deploy them to GitHub Pages — whether you prefer an automated GitHub Actions workflow or a manual process.

Export Your Notebook to WASM-Powered HTML

marimo allows you to create HTML files that run the notebook completely in your browser, powered by WebAssembly. Your notebooks can be readonly or editable:

# Export as a readonly app
marimo export html-wasm notebook.py -o output_dir --mode run
 
# Export as an editable notebook
marimo export html-wasm notebook.py -o output_dir --mode edit

For more on options, see our docs on exporting.

Publish with GitHub Actions

Automate your deployment with GitHub Actions. First, fork our template repository and add your notebooks to the appropriate folder:

• Use the notebooks directory for editable notebooks.
• Use the apps directory for readonly notebooks.

Then add a workflow file (you can call it something like .github/workflows/deploy.yml) with the following content:

jobs:
  build:
    runs-on: ubuntu-latest
 
    steps:
      # ... checkout and install dependencies
      - name: Export notebook
        run: marimo export html-wasm notebook.py -o path/to/output --mode run
 
      - name: Upload Pages Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: path/to/output
 
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
 
    permissions:
      pages: write
      id-token: write
 
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
        with:
          artifact_name: github-pages

This setup will rebuild and deploy your notebook every time you push changes.

Publish Manually

If you prefer manual control, simply export your notebook as shown above, then push the generated output to your GitHub repository. Make sure you also include a .nojekyll file at the root of your output folder. This avoids any interference from GitHub’s Jekyll engine.

For more details on manual deployment, check out GitHub’s documentation.

Conclusion

With marimo’s export features and GitHub Pages’ free hosting, you can share fully interactive notebooks with the world in minutes. Experiment with both the readonly and editable modes to see what fits your needs best.

Happy publishing!

Join the marimo community

If you're interested in helping shape marimo's future, here are some ways you can get involved: