Jupyter notebooks

You can use the Modal client library in notebook environments like Jupyter! Just import it and use as normal. However, there are some limitations to this.

Known issues

  • Modal functions must be defined and executed within a single notebook cell.

    Currently you cannot spread your Modal functions and stub.run() app execution across multiple cells. Code from other cells can be referred to, but all @stub.function() decorations should be in a single cell.

  • Modal functions can only be called remotely.

    Invoking the wrapped function locally does not work.

    @stub.function()
    def f():
        return "hello"
    
    with stub.run():
        assert "hello" == f.remote()  # remote call works ✔️
        f()  # raises error in notebook ⚠️
  • Interactive shell and interactive functions are not supported.

    These can only be run within a live terminal session, so they are not supported in notebooks.

If you encounter issues not documented above, first check your Modal client version is >=0.49.2142. Also, try restarting the notebook kernel, as it may be in a broken state, which is common in notebook development.

If the issue persists, contact us in Slack.

We are working on removing these limitations so that writing Modal applications in a notebook feels just like developing in regular Python modules and scripts.

Jupyter inside Modal

You can also run Jupyter from inside a Modal function. This gives you a serverless Jupyter environment with flexible CPU, GPU, and memory resources. It’s an interactive development session that can be allocated only when you need it.

Jupyter listens on a port in your container. We don’t have a built-in way to expose these ports to the public Internet yet.

Further examples