Skip to content

Using Multiple Python Versions and Environments with RStudio Workbench and Jupyter Notebooks#

Overview#

RStudio Workbench, formerly RStudio Server Pro1, versions 1.2.5 and higher include the ability to use Jupyter Notebooks and JupyterLab.

In addition to the Python version and environment that is used in the RStudio Workbench configuration, you can configure additional Python versions and environments using the following steps.

Prerequisites#

  • RStudio Workbench 1.2.5 and higher installed and configured with Jupyter Notebooks and one version of Python
  • Determine if you want to add a new Python version or environment for all users:
    • Method 1: requires administrator access, OR
    • Method 2: is only for your user

Method 1 - Install additional Python version for all users#

For administrators

Administrators can use this method to install an additional version of Python that is available globally to all users.

Step 1. Install additional Python version#

  • Install an additional version of Python on the server following the steps to Install Python.

    Info

    Our recommended installation instructions for Python allow you to make multiple versions of Python available and avoid replacing existing versions of Python when updating system packages.

Step 2. Install the ipykernel package#

  • From the previous step, you should still have the PYTHON_VERSION environment variable defined with the version of Python that you installed. If not, you can define this environment variable before proceed by running the following command and replacing 3.7.7 with the new version of Python that you installed:

    Terminal
    export PYTHON_VERSION=3.7.7
    

  • Install the ipykernel Python package in the root of your newly installed Python environment using the following command:

    Terminal
    $ sudo /opt/python/${PYTHON_VERSION}/pip install ipykernel
    

Step 3. Register additional Python version as a new kernel#

  • Register the additional version of Python as a new kernel using the following command:

    Terminal
    $ sudo /opt/python/${PYTHON_VERSION}/bin/python -m ipykernel install --name py${PYTHON_VERSION} --display-name "Python ${PYTHON_VERSION}"
    

Step 4. Verify the new kernel in Jupyter#

  • From your browser, navigate to the RStudio Workbench interface and log in.
  • Select New Session and do the following:

  1. Give your session a name.
  2. In the Editor field, Select either Jupyter Notebooks or JupyterLab as the IDE.
  3. Click Start Session.

A screenshot of the Jupyter Notebook Local Plugin UI that displays the New Session configuration panel and the new session's Editor configured using the Jupyter Notebook option.

  • From the menu bar, click Kernel > Change Kernel and select the newly installed kernel.

    Install additional versions of Python

    Repeat the steps in this section to install additional Python versions and environments that will be available to all users.

Method 2 - Register an additional Python environment only for your user#

For users

Users can use this method to register an additional Python environment that is available only to their user.

Step 1. Create virtual environment#

  • Open a Terminal in Jupyter Notebook or Jupyter Lab and create a virtual environment.

    Terminal>
    $ /opt/python/${PYTHON_VERSION}/bin/virtualenv ~/venvs/my_environment
    
    # Optionally add a --python flag to set the Python version
    $ /opt/python/${PYTHON_VERSION}/bin/virtualenv ~/venvs/my_environment --python /opt/python/${PYTHON_VERSION}/bin/python3
    

  • Replace the following:

    • ${PYTHON_VERSION} with the version of Python you want to use
    • ~/venvs/my_environment with the location you want to use for your virtual environment, this directory should be in your home directory

Step 2. Install the ipykernel package#

  • Install the ipykernel Python package in the Python environment that you want to use from Jupyter Notebooks in RStudio Workbench using the following command:

    Terminal
    $ ~/venvs/my_environment/bin/pip install ipykernel
    

  • Replace ~/venvs/my_environment/bin/pip with the path to pip in the environment that you want to use from Jupyter Notebooks in RStudio Workbench.

  • Optionally install any other libraries you want to be available in that virtual environment:

    Terminal>
    $ ~/venvs/my_environment/bin/pip install pandas matplotlib
    

  • Or if you manage dependencies using a requirements.txt file:

    Terminal>
    $ ~/venvs/my_environment/bin/pip install -r requirements.txt
    

Step 3. Register additional Python version as a new kernel#

  • Register the additional Python environment as a new kernel using the following command:

    Terminal
    $ ~/venvs/my_environment/bin/python -m ipykernel install --name my-python-env --display-name "Custom Python environment" --user
    

  • Replace ~/venvs/my_environment/bin/python with the path to Python in the environment that you want to use from Jupyter Notebooks in RStudio Workbench.

  • You can change my-python-env and Custom Python Environment in the above command to your desired kernel name and display name.

Step 4. Verify the new kernel in Jupyter#

  • From your browser, navigate to the RStudio Workbench interface and log in.
  • Select New Session and do the following:

  1. Give your session a name.
  2. In the Editor field, Select either Jupyter Notebooks or JupyterLab as the IDE.
  3. Click Start Session.

A screenshot of the Jupyter Notebook Local Plugin UI that displays the New Session configuration panel and the new session's Editor configured using the Jupyter Notebook option.

  • From the menu bar, click Kernel > Change Kernel and select the newly installed kernel.

    Additional Python environments

    You can repeat the steps in this section to install additional Python environments that will be available only to your user.

Publishing Jupyter Notebooks to RStudio Connect#

  • If you are using the rsconnect_jupyter Python package to deploy content to RStudio Connect and using multiple Python environments you have to:

    • Install the rsconnect_jupyter Python package and enable the server extension in the global Python environment that RSW is configured for:

      Terminal
      $ /opt/python/3.7.7/bin/pip install rsconnect_jupyter
      
      # Enable Python extension
      $ /opt/python/3.7.7/bin/jupyter-serverextension enable --sys-prefix --py rsconnect_jupyter
      

    • Install the rsconnect_jupyter Python package and enable the notebook extension on each environment:

      Terminal
      $ ~/venvs/my_environment/bin/pip install rsconnect_jupyter
      
      # Install `rsconnect-jupyter` as a jupyter extension
      $ ~/venvs/my_environment/bin/jupyter-nbextension install --sys-prefix --py rsconnect_jupyter
      
      # Enable JavaScript extension
      $ ~/venvs/my_environment/bin/jupyter-nbextension enable --sys-prefix --py rsconnect_jupyter
      

For more information refer to the documentation for rsconnect_jupyter.

Troubleshooting RStudio Workbench and Jupyter#

Refer to the support article on troubleshooting Jupyter Notebooks in RStudio Server Pro for additional information on troubleshooting RStudio Workbench with Jupyter.

Additional Documentation#

For more information on RStudio Workbench and Jupyter Notebooks, refer to the following reference documentation:

For more information on using Jupyter kernels for different environments and kernel specs, refer to the following reference documentation:


  1. We have renamed RStudio Server Pro to RStudio Workbench. This change reflects the product’s growing support for a wide range of different development environments. RStudio Workbench enables R and Python data scientists to use their preferred IDE in a secure, scalable, and collaborative environment -- whether that is the RStudio IDE, JupyterLab, Jupyter Notebooks, or VS Code. We want RStudio Workbench to be the best single platform to support open source, code-first data science, whether your team is using R or Python. Please see our official Announcement and review our FAQ regarding the name change from RStudio Server Pro to RStudio Workbench.