Pyenv

The Posit, PBC Solutions Engineering Team recommends using pyenv to manage your different Python versions. You can find their guide here:

https://solutions.posit.co/write-code/minimum-viable-python/installing-python/

For MacOS and Linux, The official pyenv repository and installation instructions are here: https://github.com/pyenv/pyenv

For Windows you can find the official instructions here: https://github.com/pyenv-win/pyenv-win

Below, is a more focused guide on setting up Python using pyenv on your machine.

1 OS Specific Installation Notes

1.1 MacOS

There are a few ways you can install pyenv on a mac:

1. Homebrew
2. Automatic installer with shell script
3. Directly from the GitHub repository

We recommend using Homebrew, if you have it installed, otherwise, the shell script.

1.1.1 Method 1 (Recommended): MacOS Homebrew

If Homebrew is installed, you can run the following commands in the terminal to install pyenv.

brew update
brew install pyenv

1.1.2 Method 2: Shell Script

The pyenv-installer project has provided a one line command to download and run the pyenv installer script.

curl https://pyenv.run | bash

1.1.3 Post installation setup

There are 2 main steps in the post installation setup:

1. Prep your shell environment
2. Install the dependencies for installing Python

Prep your shell environment

Macs default to zsh as the shell. Assuming this is the shell you are using, you can initialize pyenv with the following commands

# standard pyenv install
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

# pyenv rstudio and reticulate settings
echo 'PYTHON_CONFIGURE_OPTS="--enable-shared"' >> ~/.zshrc

Important

It’s important that you set PYTHON_CONFIGURE_OPTS="--enable-shared" if you are planning to use pyenv Python installations with the R {reticulate} package. You will get a message within RStudio too if you try to load up python that does not have the PYTHON_CONFIGURE_OPTS variable set. We are putting the setting into the ~/.zshrc so this behavior is a default. Otherwise you will need to export the variable before installing python with pyenv install.

Restart your shell by closing and opening a new terminal, or by running the following command

exec "$SHELL"

Install the dependencies for installing Python

Make sure you have the Xcode Command Line Tools

xcode-select --install

Then install the python dependencies (recommended using brew)

brew install openssl readline sqlite3 xz zlib tcl-tk

You should be ready to install Python. Head over to the Install Python section!

1.1.4 Confirm installation

You can confirm your installation with:

pyenv --version

1.2 Windows

We need to look at the pyenv-win project to install pyenv for windows. You can find the link to the project here:

https://github.com/pyenv-win/pyenv-win

There are a few methods of installing pyenv-win on Windows.

1. Using the Windows PowerShell
2. Manual installation from zip
3. Using a windows package manager (e.g., chocolatey, scoop)

1.2.1 Method 1: Windows Powershell

You can run the following command in the PowerShell terminal:

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"

If you see an UnauthorizedAccess error you need to:

1. Open Windows PowerShell with the “Run as administer” option
2. Run the following command:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine

If you are getting a “not digitally signed” error, you may also need to unblock the pyenv script:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
Unblock-File (Join-Path $env:PYENV 'bin/pyenv.ps1')

1.2.2 Method 2: Manual installation

1. Download pyenv-win.zip

2. Create a .pyenv folder in your home directory. In PowerShell or Git Bash:

mkdir $HOME/.pyenv

3. Extract the pyenv-win.zip contents into the newly created .pyenv directory you just created

4. You should have a a bin/ directory in $HOME/.pyenv/pyenv-win/bin

1.2.3 Method 3: Package Managers

You can install pyenv-win using one of the Windows Package managers:

1. Chocolatey: https://chocolatey.org/install
2. Scoop: https://scoop.sh/

At the time of writing, pyenv-win is not in the winget repositories

Chocolatey

choco install pyenv-win

Scoop

scoop bucket add main
scoop install main/pyenv

1.2.4 Post installation setup

You need to add a few variables into your Environment Variables. You can do this by pressing the windows key and searching for the “Edit environment variables for your account”. Or you can run the commands in PowerShell to add them.

In general you need to add 3 pyenv variables and append a directory to the Path. The PYENV, PYENV_HOME, and PYENV_ROOT user variables need to all point to your pyenv-win directory within your .pyenv folder in your home directory.

[System.Environment]::SetEnvironmentVariable('PYENV',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
[System.Environment]::SetEnvironmentVariable('PYENV_ROOT',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
[System.Environment]::SetEnvironmentVariable('PYENV_HOME',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")

The .pyenv\pyenv-win\bin\ directory also needs to be added to the beginning of the Path variable

[System.Environment]::SetEnvironmentVariable('path', $env:USERPROFILE + "\.pyenv\pyenv-win\bin;" + $env:USERPROFILE + "\.pyenv\pyenv-win\shims;" + [System.Environment]::GetEnvironmentVariable('path', "User"),"User")

1.2.5 Confirm installation

You can confirm your installation with:

pyenv --version

You should not be seeing any “command not found” errors. Opening things in a new terminal or restarting applications may help.

1.3 Linux

You can check to see if your current version of linux has pyenv in its package manager. Otherwise, you will install pyenv using the automatic installer script.

Ubuntu

sudo apt update
curl https://pyenv.run | bash

Arch

pyenv exists in the Arch Extra repository: https://archlinux.org/packages/extra/any/pyenv/

pacman -Syu pyenv

1.3.1 Post installation setup

Edit your ~/.bashrc as follows when running Linux - and note the special instructions for WSL.

Linux Native (Bash)

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

exec $SHELL
pyenv --version

Ubuntu (WSL)

But note that if you run Linux using WSL on Windows (why?), you must do the following instead:

echo 'export PYENV_ROOT="$HOME/.pyenv"'
echo 'export PATH="$PYENV_ROOT/bin:$PATH"'
echo 'eval "$(pyenv init -)"'

exec $SHELL
pyenv --version

2 Install Python

We’ll be using pyenv to install Python.

First, we need to know what version of Python you want to install. Luckily, pyenv can list out all the versions available to you by typing

pyenv install --list

Usually you know roughly some version of Python you may already want to install, but not the exact number. You can filter the results with a match

MacOS / Linux / Git Bash

pyenv install --list | grep 3.11

Windows Powershell

 pyenv install --list | select-string 3.11

This will list all the Python 3.11 patch versions for you.

If you want to install the latest Python version, you only need to specify the major number, 3.

pyenv install 3

You can list all the pyenv installed versions with:

pyenv versions

3 Install Packages

We recommend that you try to keep your base python version as clean as possible, i.e., do not install any packages into it. Instead, please head over to the Virtual Environments page page and install your packages into a virtual environment.