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.

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.12.4"

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

Upgrade required Python tools

When installing Python on a Posit Connect server, 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, while pip and setuptools are used to install Python packages.

Note

When using Python >= 3.12, the setuptools module is no longer installed by default.

Connect requires that users have updated versions of these Python tools. To install and upgrade the required tools, run the following command¹:

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

(Optional) Configure a PyPI repository

To specify a default PyPI mirror for all installations of Python, create
a pip configuration file. This can be useful if you are using an internal PyPI mirror such as Posit Package Manager:

Create a file located at /etc/pip.conf containing:

File: /etc/pip.conf

[global]
index-url = https://company.example.com/pypi/latest

Replace https://company.example.com/pypi/latest with the URL of your PyPI mirror, available in Package Manager on the Setup page of your PyPI repository.

(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 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 Python local certificate authority trust

Add the root CA certificate to the system trust store for Python on 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 Posit Workbench like this:

Red Hat/CentOS

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

Ubuntu/Debian

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.

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.