Skip to content
Get packs

Guide · Open source

How to use pyenv: install and switch Python versions

Updated · written with AI from the project's own documentation and checked against our catalogue data

pyenv is a free, MIT-licensed command-line tool for installing several versions of Python on one computer and switching between them. This guide is for people on Linux, macOS or WSL who need different Python versions for different projects. By the end you will know how to install pyenv, set it up in your shell, install a Python version and choose which one runs.

pyenvpyenv/pyenv · ★ 45.2k · MIT

Quick start

  1. 1Check your system. Confirm you are on Linux, macOS or WSL. Pyenv does not officially support native Windows.
  2. 2Install pyenv. Run the automatic installer on Linux or Unix, or use Homebrew on macOS.
  3. 3Add shell setup. Run the init command with --install so your startup files load pyenv.
  4. 4Restart your shell. Run exec "$SHELL" so the PATH changes take effect.
  5. 5Install build dependencies. Install the suggested build dependencies from the pyenv wiki before building Python.
  6. 6Install a Python version. Use pyenv install to add a version, then choose it with pyenv global or pyenv local.

Install pyenv on Linux, Unix or macOS

On Linux or other Unix-like systems, the README recommends its automatic installer. The installer is run with curl and piped to bash.

On macOS, the README recommends Homebrew. Update Homebrew first, then install pyenv. Pyenv can also be installed with a basic GitHub checkout into a folder such as $HOME/.pyenv, which needs git.

  • Automatic installer: recommended on Linux and Unix.
  • Homebrew: recommended for basic use on macOS.
  • GitHub checkout: makes it easy to fork and contribute changes; git is required.
curl -fsSL https://pyenv.run | bash

Set up your shell for pyenv

Pyenv needs a few lines in your shell startup files so that its shims directory is on your PATH. The README says the setup below works for most common use cases. If you installed with the installer script, run the init command from its full path. If you installed with Homebrew, the plain pyenv command works.

After adding the setup, restart your shell so the PATH changes take effect. Then install the build dependencies listed in the pyenv wiki before you install a new Python version.

  • Installer script: ~/.pyenv/bin/pyenv init --install
  • Homebrew: pyenv init --install
  • Restart the shell with: exec "$SHELL"
  • For Bash, if BASH_ENV points to .bashrc, use the manual Bash instructions instead of the automatic --install path.
~/.pyenv/bin/pyenv init --install

Install and choose a Python version

Use pyenv install to download and build an additional Python version. Pyenv supports several distributions, including CPython, PyPy, Stackless Python and Jython. The README also notes that you can use a prefix to let pyenv resolve to the latest matching version.

To switch versions, pyenv works in layers. A global version applies to your user account. A per-project version applies when you are inside that project. An environment variable can override both. Use pyenv global to set the account default and pyenv local to set a project version.

  • pyenv global: sets the default Python for your user account.
  • pyenv local: sets a version for a specific project.
  • An environment variable can override the version for a single session.

Test across several Python versions

Pyenv can search for commands across multiple Python versions at a time. The README says this can help when you test across Python versions with tox.

  • Use tox to run the same test suite under several Python versions.
  • Pyenv does not manage virtual environments itself; pyenv-virtualenv is a separate project for that.

Understand shims and PATH

Pyenv does not need to be loaded as a shell function to work. Its shim approach adds a directory to your PATH. Each shim is a small wrapper program that sends the command to the Python version pyenv has selected. The tool is written in pure shell scripts, so it does not depend on Python being installed first.

  • Shims: small wrapper programs placed on PATH.
  • Built from shell scripts, with no Python bootstrap needed.

Uninstall pyenv or upgrade it

Upgrade steps depend on how you installed pyenv. Homebrew users upgrade through Homebrew, while installer and Git checkout users follow the upgrade section of the README. Pyenv also has an uninstall section and a plugin system.

  • Homebrew users: upgrade through brew.
  • Installer or Git checkout users: follow the README upgrade section.

What people use it for

  • Keep one project on Python 3.8 and another on a newer release on the same computer.
  • Test a library across several Python versions with tox.
  • Keep a per-user Python setup on macOS without changing the system Python.
  • Try alternative distributions such as PyPy on a Unix-like system.

Frequently asked questions

Does pyenv work on Windows?

The README says pyenv does not officially support Windows and does not work outside WSL. Under WSL, the Pythons it installs are Linux builds. For native Windows Python, the maintainers point to pyenv-win.

Is pyenv free?

Yes. The pyenv/pyenv project is licensed under the MIT License.

What do I need to install pyenv?

You need a Unix-like system such as Linux or macOS, or WSL on Windows. Git is needed if you use the GitHub checkout method.

Does pyenv manage virtual environments?

No. The README says pyenv does not manage virtualenv. You can create virtualenvs yourself or use the separate pyenv-virtualenv project.

What is the difference between pyenv global and pyenv local?

pyenv global sets the default Python version for your user account. pyenv local sets a version for a specific project directory, and it takes precedence in that project.

What are alternatives to pyenv?

The README compares it with pythonbrew and pythonz. Other projects mentioned in the comparison list include pyenv-win for Windows and asdf.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

pyenv suits developers on Linux or macOS who switch between Python versions for different projects or test across versions with tox. If you use native Windows, want built-in virtual environment management, or need native Windows Python builds, pick pyenv-win or another tool.

Install options & downloads