Python

Install and switch Python versions with pyenv

Keep several Python versions on one computer and pick which one each project uses, without touching the Python your system needs.

Fill these in once
  1. Install pyenv
    Terminal
    brew install pyenv

    This uses Homebrew.

  2. Load pyenv in every new terminal
    Terminal
    echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
    echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
    echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc

    Then close this terminal and open a new one so the change takes effect.

  3. See which versions you can install
    Terminal
    pyenv install --list

    The list is long. Plain numbers like 3.12.7 are the standard Python releases.

  4. Install a version
    Terminal
    pyenv install 3.12.7

    pyenv builds Python from source, so this can take a few minutes.

  5. Use it everywhere by default
    Terminal
    pyenv global 3.12.7
  6. Use it in one project only
    Terminal
    pyenv local 3.12.7

    Run this inside the project folder. It writes a .python-version file there, and pyenv switches to that version whenever you are in the folder.

  7. List the versions you have
    Terminal
    pyenv versions

    The one with a star is the version in use right now.

Check it worked

  1. Check which Python runs
    Terminal
    python --version
  2. Check the Python comes from pyenv
    Terminal
    pyenv which python
Undo it
  1. Go back to the system Python
    Terminal
    pyenv global system
  2. Remove a version you installed
    Terminal
    pyenv uninstall -f 3.12.7
  1. Install the build tools Python needsNeeds sudo
    Terminal · Ubuntu / Debian
    sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev libffi-dev liblzma-dev tk-dev

    This is for Ubuntu and Debian. pyenv builds Python from source and fails without these. Other systems need the same libraries from their own package manager.

  2. Install pyenv
    Terminal · Ubuntu / Debian
    curl -fsSL https://pyenv.run | bash

    This downloads the official pyenv installer and puts pyenv in ~/.pyenv.

  3. Load pyenv in every new terminal
    Terminal · Ubuntu / Debian
    echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
    echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
    echo 'eval "$(pyenv init - bash)"' >> ~/.bashrc

    Then close this terminal and open a new one so the change takes effect.

  4. See which versions you can install
    Terminal · Ubuntu / Debian
    pyenv install --list

    The list is long. Plain numbers like 3.12.7 are the standard Python releases.

  5. Install a version
    Terminal · Ubuntu / Debian
    pyenv install 3.12.7

    pyenv builds Python from source, so this can take a few minutes.

  6. Use it everywhere by default
    Terminal · Ubuntu / Debian
    pyenv global 3.12.7
  7. Use it in one project only
    Terminal · Ubuntu / Debian
    pyenv local 3.12.7

    Run this inside the project folder. It writes a .python-version file there, and pyenv switches to that version whenever you are in the folder.

  8. List the versions you have
    Terminal · Ubuntu / Debian
    pyenv versions

    The one with a star is the version in use right now.

Check it worked

  1. Check which Python runs
    Terminal · Ubuntu / Debian
    python --version
  2. Check the Python comes from pyenv
    Terminal · Ubuntu / Debian
    pyenv which python
Undo it
  1. Go back to the system Python
    Terminal · Ubuntu / Debian
    pyenv global system
  2. Remove a version you installed
    Terminal · Ubuntu / Debian
    pyenv uninstall -f 3.12.7
  1. Install pyenv-win
    PowerShell
    winget install -e --id pyenv-win.pyenv-win

    pyenv itself doesn't run on Windows, so this is pyenv-win, a version made for Windows. You can also use the PowerShell installer from the pyenv-win README. Open a new terminal afterwards.

  2. See which versions you can install
    PowerShell
    pyenv install --list
  3. Install a version
    PowerShell
    pyenv install 3.12.7
  4. Use it everywhere by default
    PowerShell
    pyenv global 3.12.7
  5. Use it in one project only
    PowerShell
    pyenv local 3.12.7

    Run this inside the project folder. It writes a .python-version file there, and pyenv switches to that version whenever you are in the folder.

  6. List the versions you have
    PowerShell
    pyenv versions

    Prefer not to install anything? Windows already has the py launcher, which picks a version you installed from python.org, for example py -3.12.

Check it worked

  1. Check which Python runs
    PowerShell
    python --version
  2. Check the Python comes from pyenv
    PowerShell
    pyenv which python
Undo it
  1. Remove a version you installed
    PowerShell
    pyenv uninstall 3.12.7

    pyenv-win has no system option, so removing the version is how you stop using it.