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.ipynbNotebook 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.csvPackage 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.ipynbYou 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=freezeinteractive (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.ipynbYou 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.ipynbCreating 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.ipynbManifests for static (pre-rendered) notebooks cannot be created.