Jupyter Notebooks

Using the rsconnect CLI

Here’s an example command that deploys a Jupyter notebook to Posit Connect, assuming that you set up a server named myServer when configuring your account:

rsconnect deploy notebook -n myServer my-notebook.ipynb

Notebook Deployment Options

There are a variety of options available to you when deploying a Jupyter notebook to Posit Connect.

Including Extra Files

You can include extra files in the deployment bundle to make them available when your notebook is run by the Posit Connect server. Just specify them on the command line after the notebook file:

rsconnect deploy notebook my-notebook.ipynb data.csv

Package Dependencies

If a requirements.txt file exists in the same directory as the notebook file, it will be included in the bundle. It must specify the package dependencies needed to execute the notebook. Posit Connect will reconstruct the Python environment using the specified package list.

If there is no requirements.txt file or the --force-generate option is specified, the package dependencies will be determined from the current Python environment, or from an alternative Python executable specified via the --python option or via the RETICULATE_PYTHON environment variable:

rsconnect deploy notebook --python /path/to/python my-notebook.ipynb

You can see the packages list that will be included by running pip list --format=freeze yourself, ensuring that you use the same Python that you use to run your Jupyter Notebook:

/path/to/python -m pip list --format=freeze

Interactive (Voila) Deployment

By default, Connect renders Jupyter notebooks into HTML documents. If your notebook includes interactive widgets (ipywidgets), deploy using Voila mode to present the notebook interactively using Voila.

Interactive mode runs the notebook each time a user visits it, and maintains a live Jupyter kernel so that the user can interact with your code via interactive widgets.

You can run your notebook locally using Voila from the command line (voila notebook.ipynb) or via the Voila extension for Jupyter. Running your notebook locally is helpful to identify issues before deploying.

Supported Content

Notebooks that use ipywidgets for interactivity can be deployed to Connect. Other kinds of active content, such as embedded applications and APIs, are not supported.

When you are ready to deploy an application that you developed in a notebook, first export the notebook from Jupyter into a separate .py file using the “File > Export Notebook As… > Executable Script” menu item. Then deploy the file using rsconnect-python.

Deploying

To deploy to Connect:

rsconnect deploy voila my-notebook.ipynb

You can also deploy a directory containing notebooks in Voila mode. Visitors will see a list of notebooks and can select which one to open.

rsconnect deploy voila --multi-notebook ./

Theming and Customization

You can customize your Voila deployment by including a voila.json file in your deployment directory. See the voila documentation for details.

If you use a custom JupyterLab theme with Voila as described in the documentation, be sure to include the theme package in your requirements.txt file. This ensures that Connect installs it in the virtual environment where your notebook will be run.

Jupyter Kernels

Voila automatically spawns a Jupyter kernel when a user visits a deployed Voila notebook. Kernel processes are terminated when the user sessions ends, for example by closing the browser tab. When the user visits the notebook again, Voila will start a new session with a new kernel.

Note

Voila’s kernel preheating option enables you to start up one or more Jupyter kernels and execute initialization code before users visit your deployed notebook. Connect may spawn multiple processes to serve user requests, based on the settings in the Runtime tab. Each worker process will have its own set of preheated kernels.

Troubleshooting

If there are problems executing code in an interactive notebook, Voila suggests using the --debug flag to show details about the error. You can enable Voila debugging in Connect using the Environment Variables panel. Defining an environment variable named DEBUG with any non-empty value will enable debugging.

Static (Snapshot) Deployment

By default, rsconnect deploys the original notebook with all its source code. This enables the Posit Connect server to re-run the notebook upon request or on a schedule.

If you just want to publish an HTML snapshot of the notebook, you can use the --static option. This will cause rsconnect to execute your notebook locally to produce the HTML file, then publish the HTML file to the Posit Connect server:

rsconnect deploy notebook --static my-notebook.ipynb

Creating a Manifest for Future Deployment

You can create a manifest.json file for a Jupyter Notebook, then use that manifest in a later deployment. Use the write-manifest command to do this.

The write-manifest command will also create a requirements.txt file, if it does not already exist or the --force-generate option is specified. It will contain the package dependencies from the current Python environment, or from an alternative Python executable specified in the --python option.

Here is an example of the write-manifest command:

rsconnect write-manifest notebook my-notebook.ipynb

Note

Manifests for static (pre-rendered) notebooks cannot be created.