Python

Off-Host Execution

When using off-host execution, Python versions are defined by the set of Execution Environments available for executing content. For an overview of this feature, please see the Execution Environments appendix. Connect selects an appropriate image from the set of configured images based on the version of Python requested by the content.

Posit Connect offers a flexible way of deploying Python APIs, web apps such as Dash and Streamlit, Jupyter Notebooks, and reticulated R content against a variety of Python versions.

A compatible version of Python is identified when content is deployed. That Python installation is used any time Python is needed for that content. Package installation and rendering content that utilizes Python uses the version of Python discovered at deploy-time.

Connect allows different content to rely on different versions of Python. For example, Alice’s Flask API might require version 3.9.7 of Python while Bob’s Shiny application with reticulate needs Python version 3.8.1. Those two deployments using different Python versions can coexist in Connect without conflict.

This chapter discusses how to install Python, how Connect can be configured to support one or more versions of Python, how Python version compatibility is determined, and other configuration settings relevant to Python support in Connect.

Available Python installations are analyzed at startup. Connect logs the provided Python versions and whether it can use each installation.

Changing any of the configuration items discussed in this chapter requires a restart of Connect.

Additional Requirements

Each Python installation is required to have the pip, venv, and setuptools packages installed. The Python venv module is used to create content-specific environments and pip and setuptools are used to install Python packages. See the Python installation instructions for guidance on configuring Python installations for Connect.

Enabling Python Support

Python support is disabled by default but can be enabled by setting the Python.Enabled property to true.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Python]
Enabled = true

Posit Connect also needs to be configured to use a specific Python installation in order to fully support Python content.

The Python.Executable property is used to specify locations for Python installations. Specify this property once for each Python installation directory.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Python]
Enabled = true
Executable = /shared/Python/3.8.1/bin/python3
Executable = /shared/Python/3.9.7/bin/python3

Note

The Python.Executable property is permitted to be a symbolic link to a Python installation.

Installing Python

The minimum Python version supported is 3.8.0.

See Installing Python to learn how to install Python.

Note

We do not recommend installing Python with a package manager like apt, yum, or zypper.

Once you have Python installed on the server, it is important to understand how Connect discovers Python and chooses the Python version that an asset uses. Python Version Matching explains more about this process.

Upgrading Python

We strongly recommend supporting multiple versions of Python instead of upgrading and maintaining a single version of Python. Supporting multiple versions of Python is the best way to ensure applications or reports published with specific package dependencies continue to run.

After installing another Python version:

Stop Posit Connect
Add an additional Python.Executable property to the configuration file that points to the newly built Python installation.
Start Posit Connect

Following an upgrade, content dependent on Python is rebuilt on-demand. For example, during the next execution of a scheduled Jupyter Notebook, Posit Connect automatically reinstalls and rebuilds all of the necessary packages before rendering the report, if needed. During the package updates, Connect presents a message and spinner indicating to the end user that the rendered Jupyter Notebook is available once the packages are successfully installed and built for the new version of Python.

Rebuilding and restoring packages can take a significant amount of time and can delay or prevent the rendering of a report or the availability of applications. You can proactively rebuild Python or R content using the rsconnect content build command included with the rsconnect-python Python package.

Note

Not all packages can be reinstalled and rebuilt on newer versions of Python. Rebuilding and restoring packages can take a significant amount of time and can delay or prevent the rendering of a Jupyter Notebook or reticulated R content.

Python Version Matching

Posit Connect attempts to find a Python installation that is appropriate for your content. By default, it applies a “major-minor” matching approach. This algorithm attempts to find a version of Python to use with your content. More deployments are successful but not always with the same version of Python that is used by the author.

If you would prefer a strict association between authored and deployed Python versions, you can choose to use an “exact” matching approach.

The major-minor algorithm requires exact MAJOR.MINOR matching but is flexible about the patch level. This is a useful option when your desktop and server may occasionally have different update cycles when installing bug fix releases. For example, if content is deployed with Python 3.10.0 and Connect is configured with Python 3.10.1, then Python 3.10.1 will be used as the MAJOR.MINOR numbers match (3.10 and 3.10). But, if Connect is configured with only Python 3.9.7, then the content will fail to deploy as the MAJOR.MINOR versions are different (3.10 vs. 3.9).

An inconsistent version of Python occasionally causes problems when installing package dependencies. For the best results, make sure that Connect has access to the same versions of Python used to author content.

The Python version matching approach is controlled with the Python.VersionMatching configuration setting.

major-minor

Find a Python installation with an exact MAJOR.MINOR version match that is close to the version used when authoring the content. If a compatible version cannot be found, content will fail to deploy.

Use exact version match.
If there are matching MAJOR.MINOR releases, use least-greater version.
If there are matching MAJOR.MINOR releases, use latest of these.

exact

Finds a Python installation that exactly matches the version of Python used when authoring the content. If a matching version cannot be found, content will fail to deploy.

Examples

The table below shows some examples of how the matching algorithm takes the version of Python used in your development environment and chooses an appropriate Python version from the ones available to Posit Connect.

Matching Algorithm	Development Version	Server Versions	Used Version	Reason
`major-minor`	3.9.6	3.9.4, 3.9.6, 3.9.9	3.9.6	Chose exact match
`major-minor`	3.9.3	3.9.1, 3.9.5, 3.9.6	3.9.5	Chose lowest 3.9.X release after 3.9.3
`major-minor`	3.8.10	3.8.4, 3.8.9, 3.9.2	3.8.9	Chose the latest 3.8.X release since all are before 3.8.10
`exact`	3.9.6	3.9.6, 3.9.7	3.9.6	Chose exact match
`exact`	3.9.6	3.9.4, 3.9.7	error	no match