Skip to content

The rsconnect-jupyter package is deprecated#

Please use rsconnect-python to publish content to Posit Connect.

rsconnect-jupyter User Guide#

The rsconnect-jupyter package is a Jupyter Notebook extension (i.e., nbextension) that provides publishing compatibility with Posit Connect.

Requirements#

Warning

This extension is not compatible with JupyterLab. Only Jupyter Notebook, and associated runtime environments, such as JupyterHub, are supported.

Warning

In order to publish to Posit Connect, a compatible Python environment must in exist on the Connect instance. See the Connect documentation on Python integrations for additional information.

Installation#

  1. Install jupyter and rsconnect-jupyter.

    Terminal
    python -m pip install jupyter rsconnect-jupyter

  2. Install the rsconnect-jupyter Jupyter Notebook extension.

    Terminal
    python -m jupyter nbextension install --sys-prefix --py rsconnect_jupyter

  3. Enable the rsconnect-jupyter Jupyter Notebook extension

    Terminal
    python -m jupyter nbextension enable --sys-prefix --py rsconnect_jupyter

  4. Enable the rsconnect-jupyter Jupyter Server extension.

    Terminal
    python -m jupyter serverextension enable --sys-prefix --py rsconnect_jupyter

Environment configuration#

Localhost (your computer)#

For localhost installation, a Python virtual environment is recommended to isolate runtime dependencies. There are various Python virtual environments available. The following tutorial covers a few of them.

Conda#

Install rsconnect-jupyter from Conda Forge.

Terminal
conda create --name rsconnect-jupyter
conda activate rsconnect-jupyter
conda install -c conda-forge jupyter rsconnect-jupyter

Next, following the installation guide.

Tip

When creating a Conda virtual environment, a specific Python version may be specified. Create your virtual environment with a Python environment that is available on your Posit Connect server.

Terminal
conda create --name rsconnect-jupyter python=3.8

Note

If Anaconda is used, then Jupyter Notebook launches with kernel environments for each existing Conda environment. Follow the installation guide for each kernel/Conda-environment to enable rsconnect-jupyter.

Python virtual environment (venv)#

Terminal
python -m venv .venv
source .venv/bin/activate

Next, following the installation guide.

Tip

Running source .venv/bin/activate activates the virtual environment. While the virtual environment is active, the .venv/bin directory is prepended to the $PATH environment variable for the active shell. Therefore executables installed within the virtual environment, like python, pip, and jupyter, are utilized. To determine which version of python, pip, or jupyter is active, execute the which command (e.g, which python).

JupyterHub#

Follow the installation guide to install and enable rsconnect-jupyter in JupyterHub.

If you've configured separate kernel environments, repeat the installation guide for each kernel environment.

Note

The exact install location depends on your JupyterHub configuration.

Quick start example#

The following example shows how to launch a Docker container running JupyterHub with the rsconnect-jupyter extension installed.

Warning

This configuration is not intended for production usage. This is a minimal working configuration designed to highlight rsconnect-jupyter configuration.

Docker Example

Create the following Dockerfile.

Dockerfile

FROM jupyterhub/jupyterhub:3

# Install Jupyter and the rsconnect-jupyter extension
RUN python3 -m pip install jupyter rsconnect-jupyter

# Enables the rsconnect-jupyter extension
RUN python3 -m jupyter nbextension install --sys-prefix --py rsconnect_jupyter
RUN python3 -m jupyter nbextension enable --sys-prefix --py rsconnect_jupyter
RUN python3 -m jupyter serverextension enable --sys-prefix --py rsconnect_jupyter

# Create a new user called "username" with the password "password".
#
# Use these credentials when logging into JupyterHub.
#
# Example:
#     username: "username"
#     password: "password"
RUN useradd -m -p $(openssl passwd -1 password) -s /bin/sh username

ENTRYPOINT ["jupyterhub"]

Next, build the Dockerfile to create a new Docker image named jupyterhub:rsconnect-jupyter.

Terminal

docker build -t jupyterhub:rsconnect-jupyter .

Finally, launch the Docker image.

Terminal

docker run --rm -p 8000:8000 --name jupyterhub jupyterhub:rsconnect-jupyter

Once executed, a series of startup logs are shown. Wait for the log message: JupyterHub is now running at http://:8000.

Once shown, the JupyterHub server is running on your local machine. To access JupyterHub, proceed with the following steps:

  1. Open http://localhost:8000 in your browser.
  2. Login to using the credentials "username" and "password". These credentials match the credentials set in the Dockerfile and can be changed.
  3. Select the New dropdown menu and select Python 3 (pykernal).
  4. Next, follow the usage guide.

Warning

At the time of writing, the jupyterhub/jupyterhub:3 Docker image is built using Python version 3.10.6. Therefore, in order to publish to Posit Connect, a compatible Python version 3.10 environment must exist in Connect.

Posit Workbench#

Posit Workbench supports Jupyter Notebook sessions. See the Jupyter Configuration guide to configure Jupyter Notebook sessions.

Once enabled, follow the installation guide to install and enable the rsconnect-jupyter plugin for each Jupyter kernel.

Copyright © Posit Software, PBC. All Rights Reserved
Posit