Install Python

How to install Python on a Linux server using uv.

uv is not Posit Software and is included in Third Party Materials (as defined in our EULA) and not covered under the Posit Support Agreement. If you download uv, you are agreeing to their license and acknowledge Posit is not responsible for uv and you are downloading uv at your sole risk.

Note

Posit no longer builds its own Python binaries. Previous Posit-built versions will remain available. Patch versions beyond Python 3.9.25 / 3.10.19 / 3.11.14 / 3.12.12 / 3.13.9 will not be built. Python 3.14 and later will not be provided.

You are not required to replace existing Python installations.

For directions on installing Python from source, see the Python documentation.

Install required dependencies

You can install standalone versions of Python using uv. Specify UV_INSTALL_DIR to change the installation location of the executable:

curl -LsSf https://astral.sh/uv/install.sh | sudo env UV_INSTALL_DIR=/usr/local/bin sh

Specify the Python version

Consult with your Python user group to determine which versions of Python they would like installed. Once defined, set the environment variable to the first Python version they request:

export PYTHON_VERSION="3.13.14"

If you are adding Python version 3.12+ to a Connect server running on version 2025.09.1 or earlier, you need to install the setuptools package by running:

sudo /opt/python/"${PYTHON_VERSION}"/bin/python -m pip install \
    --upgrade pip setuptools wheel \
    --break-system-packages \
    --root-user-action=ignore

For additional Python requirements, consult the documentation for the version of Connect you are running. See Posit Connect - supported versions for links to the version-specific documentation.

This requirement does not apply to Connect versions 2025.10+.

Download and install Python

Download and install the desired version of Python:

sudo /usr/local/bin/uv python install "${PYTHON_VERSION}" --install-dir=/opt/python
sudo ln -s /opt/python/cpython-$PYTHON_VERSION-* /opt/python/$PYTHON_VERSION

Verify Python installation

Verify that Python is installed by running the following command:

/opt/python/"${PYTHON_VERSION}"/bin/python --version

Installation of Python packages

To install Python packages into the global site-packages rather than a user’s virtual environment, use the --break-system-packages flag.1

sudo /opt/python/${PYTHON_VERSION}/bin/python -m pip install \
    ${PACKAGE_NAME} \
    --break-system-packages \
    --root-user-action=ignore

For more information, see the uv reference documentation.

Customizing the package repository

If using an alternative source of Python packages, such as Posit Package Manager, configure the package installation client in your Posit product:

(Optional) Add Python to the system PATH

Note

You can configure Python on the system PATH so that users can use pip within a terminal to install packages to their home directory, similar to how R works with install.packages().

The recommended method to add Python to the PATH is to append the version of Python that you installed to the system-wide PATH variable. For example, define this in a script within the /etc/profile.d/ directory:

cat << EOF | sudo tee /etc/profile.d/python.sh
#!/bin/bash
export PATH=/opt/python/${PYTHON_VERSION}/bin:\$PATH
EOF

(Optional) Make Python available as a Jupyter kernel

For Posit Workbench, you can make the version of Python installed available for use in Jupyter by running these commands:

sudo /opt/python/${PYTHON_VERSION}/bin/python -m pip install ipykernel --break-system-packages --root-user-action=ignore
sudo /opt/python/${PYTHON_VERSION}/bin/python -m ipykernel install --name py${PYTHON_VERSION} --display-name "Python ${PYTHON_VERSION}"

(Optional) Configure uv to use system TLS certificates

By default, uv uses a built-in certificate store rather than the operating system certificate store. If your package repository uses certificates signed by an internal Certificate Authority (CA), uv returns an error such as invalid peer certificate: UnknownIssuer.

To configure uv to use the system certificate store, add the following to /etc/uv/uv.toml:

/etc/uv/uv.toml
native-tls = true

For more details, see the uv TLS documentation. For authentication and other uv network settings, see the uv configuration reference.

(Optional) Configure Python local certificate authority trust

Add the root CA certificate to the system trust store for Python on Posit Workbench to trust internally generated certificates. See the Posit Team SSL Considerations support article for more information. Then, set the value of environment variable REQUESTS_CA_BUNDLE to the Linux system certificate store you have just updated based on the article above. You can set REQUESTS_CA_BUNDLE to the appropriate certificate bundle by updating the /etc/rstudio/launcher-env on Workbench like this:

JobType: any
Workbench: any
Environment: REQUESTS_CA_BUNDLE=/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem
JobType: any
Workbench: any
Environment: REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

For Posit Connect, use a program supervisor script to set REQUESTS_CA_BUNDLE for all applications and content that run in Connect. The Environment variables on Posit Connect article provides an example of this workflow.

(Optional) Install multiple versions of Python

To install multiple versions of Python on the same server, repeat these steps to specify, download, and install a different version of Python alongside existing versions.

Note

Use the System Requirements - Runtime support documentation of the Posit Connect Admin Guide to confirm the minimum Python version supported by Connect. If a configuration file specifies a Python 3 version lower than the minimum supported version, Connect returns an error during startup.

Uninstall

sudo unlink /opt/python/${PYTHON_VERSION}
sudo /usr/local/bin/uv python uninstall --install-dir=/opt/python $PYTHON_VERSION

Additional information

Refer to the uv Installing Python documentation for more information on installing Python.

Back to top

Footnotes

  1. --break-system-packages and --root-user-action enable the installation of packages into an environment that has been marked as externally-managed. See the pip documentation for additional information.↩︎