Python

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 venv package installed, which is used to create content-specific environments. Supported versions of Python should include venv by default.

See the Python installation instructions for guidance on configuring Python installations for Connect.

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.

Enabling Python support

The package-installed starter configuration enables Python support and scans versioned installations beneath /opt/python. Connect starts successfully when Python is enabled without a discovered installation.

If you used the Posit Python installation instructions, then you installed Python at /opt/python/<version>/bin/python3. Connect discovers this standard location without additional configuration.

If you installed Python outside a versioned directory layout, provide an Executable for each installation:

/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.

Scanning

Posit Connect can scan administrator-configured directories for Python installations and optionally use PATH.

Version scanning: Looking for Python in locations known to contain multiple version installations. Disabled by default.
Path scanning: Looking for Python using the PATH environment variable. Disabled by default, and only occurs if a Python location is not otherwise discovered or configured.

Each kind of scanning can be individually controlled. The following configuration snippet shows both scanning settings.

/etc/rstudio-connect/rstudio-connect.gcfg

[Python]
ExecutableVersionScanning = /opt/python
ExecutablePathScanning = false

Use the Python.Executable setting to explicitly enumerate Python installations.

Version scanning

Posit Connect can scan configured directories that contain multiple Python installations. Connect examines each direct child directory for a Python executable beneath its bin directory. It first checks for bin/python3, then checks for interpreter names such as bin/python or bin/python3.14t. Connect does not search nested directories.

For example, any of the following installed versions of Python will be automatically detected:

/opt/python/3.9.7/bin/python3
/opt/python/cpython-3.13-linux-x86_64-gnu/bin/python3
/opt/python/cpython-3.14+freethreaded-linux-x86_64-gnu/bin/python3.14t

Note

Symbolic links from any of these scan locations to alternate locations are permitted.

Version scanning is configured with Python.ExecutableVersionScanning, which accepts one or more absolute directory paths. It is disabled when no paths are configured.

/etc/rstudio-connect/rstudio-connect.gcfg

[Python]
; Scan direct child directories beneath /opt/python:
ExecutableVersionScanning = /opt/python

; Add an additional scan directory:
ExecutableVersionScanning = /opt/python
ExecutableVersionScanning = /opt/python-extra

; An empty value is ignored:
ExecutableVersionScanning =

Note

Use the Python.Executable setting to explicitly enumerate Python installations if your organization uses a complicated directory hierarchy.

Path scanning

Posit Connect can use the PATH environment variable to discover a version of Python if one is not otherwise found. This includes Python installations provided by the operating system package manager.

Path scanning is disabled by default and can be enabled using the Python.ExecutablePathScanning setting.

/etc/rstudio-connect/rstudio-connect.gcfg

[Python]
ExecutablePathScanning = true

Warning

Use of PATH to locate a single Python installation is not recommended for most Posit Connect installations. An environment with multiple versions of Python helps you provide a stable, reproducible environment for your Python developers.

Excluding versions

If you have versions of Python that are picked up by automatic scanning but which you would like to exclude, disable Python scanning and explicitly specify all versions you would like to use with the Python.Executable configuration property.

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 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

Note

View the Python runtime state in the Connect UI at System > Info > System Info. The page reports whether the runtime is disabled, not permitted by the license, enabled with no versions found, or enabled with discovered versions. For each local installation, the page also reports the executable path.

Restart Connect after you install a runtime version so Connect can discover the installation.

Posit Connect attempts to find a Python installation that is appropriate for published content based on the version constraint specified in the manifest.json file.

The version specification in the manifest.json is generated automatically by publishing clients such as rsconnect-python and Publisher.

Manifest Version Constraints Support

Support for manifest.json environment section was introduced in rsconnect-python v1.25.3. and Publisher v1.12.0

By default, publishing clients look for Python version information in existing .python-version or pyproject.toml or setup.cfg files, in that order.

If one is found, the manifest.json file will include an environment section with the Python version constraint respecting the PEP 440 Specification.

Example manifest.json file segment:

manifest.json

"environment": {
    "python": {
        "requires": ">=3.8,<4.0"
    }
}

When a Python version specification cannot be found in any of the environment files, the version constraint is not included in the environment section and the current Python version in use is included as is.

Example manifest.json file segment:

manifest.json

"python": {
    "version": "3.11.3"
}

For this case, Posit Connect 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

Restricting versions for new content

Supporting several Python versions keeps existing content running, but you might still want new content to target a more recent version. The Python.PublishableVersions setting takes a version specifier, using the PEP 440 Specification, that content must satisfy when it is first published:

/etc/rstudio-connect/rstudio-connect.gcfg

[Python]
PublishableVersions = ">=3.10"

Comma-separated clauses express a range, such as >=3.10,<4.0. The setting is empty by default, which places no restriction on the Python version used by new content.

The specifier takes part in Python version matching, so content that declares a range of acceptable versions is first published on a version you allow whenever one exists. Connect selects the newest installation satisfying both the content’s constraint and this setting. For example, with Python 3.9, 3.11, and 4.1 installed and PublishableVersions = "<4.0", content whose manifest.json requires >=3.9,<5.0 is first published on Python 3.11 rather than 4.1.

Publishing fails when no installed version satisfies both the content’s constraint and this setting. Connect reports that no compatible environment was found and lists the Python versions available.

The restriction applies only the first time a piece of content is published. After content has been published once, later deployments to that same content item are not restricted – including deployments that select an older, excluded version – and rebuilding an existing bundle is never restricted. Excluded Python installations therefore remain available to content that is already deployed, so existing applications and reports continue to run and you can tighten the policy without disrupting content and the maintenance of that content which predates the restriction.

Selecting Package Installer

By default, Connect uses uv pip to install Python packages. uv pip is faster than pip, and compatible with using requirements.txt files to track dependencies.

However, uv pip doesn’t support the full set of options provided by pip. See UV compatibility with pip.

To revert to using pip, set Python.AllowUv=false in Connect configuration file:

/etc/rstudio-connect/rstudio-connect.gcfg

[Python]
AllowUv = false