Jupyter Notebook

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 Connect.

Including extra files

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

rsconnect deploy notebook my-notebook.ipynb data.csv

Hide input

There are two options for hiding input code cells in Jupyter Notebooks published to Connect:

Hide all input code cells

Deploy the notebook with the --hide-all-input option to hide all input code cells:

rsconnect deploy notebook my-notebook.ipynb --hide-all-input

Hide only selected input code cells

To hide only the tagged cells, first enable Tags in the View > Cell Toolbar menu:

Enable Tags in the Cell Toolbar menu.

Once enabled, tag each cell where you want to hide the input code. You must name the tag hide_input:

  1. In the text field, type “hide_input”.

  2. To apply the tag to the code cell, click Add tag.

    Add the hide_input tag to individual cells with the 'Add tag' input.

rsconnect deploy notebook my-notebook.ipynb --hide-tagged-input

Package dependencies

If a requirements.txt file exists in the same directory as the notebook file, it is included in the bundle. It must specify the package dependencies needed to execute the notebook. Connect reconstructs 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 are determined from the current Python environment, 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 list of packages that are 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 Voilà mode to present the notebook interactively using Voilà. For more information, see the Interactive Documents section.

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 Voilà mode. Visitors can see a list of notebooks and 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 voilà documentation for details.

If you use a custom JupyterLab theme with Voilà as described in the Voilà 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 is run.

Jupyter kernels

Voilà automatically spawns a Jupyter kernel when a user visits a deployed Voilà notebook. Kernel processes are terminated when the user sessions ends (e.g., by closing the browser tab). When the user visits the notebook again, Voilà starts a new session with a new kernel.

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

Troubleshooting

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

Static (snapshot) deployment

By default, rsconnect deploys the original notebook with all its source code. This enables the 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 causes rsconnect to execute your notebook locally to produce the HTML file, then publish the HTML file to the 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 also creates a requirements.txt file, if it does not already exist or the --force-generate option is specified. It contains 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.