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
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
Manifests for static (pre-rendered) notebooks cannot be created.