Pyenv is a tool for managing different Python versions.
Whether you’re upgrading a project to a newer Python release or switching between projects with different requirements, pyenv makes the process simple and hassle-free.

Installation

You can install pyenv with Homebrew, following the official instructions .
Windows is not supported, but there is an alternative project: pyenv-win .

brew install pyenv

Verify the installation:

pyenv versions

After installation, you’ll need to configure your shell.

For bash users:

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

For zsh users:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

If you forget the setup commands, you can run pyenv init to check the instructions. The output will look like this:

# Load pyenv automatically by appending
# the following to
# ~/.zprofile (for login shells)
# and ~/.zshrc (for interactive shells) :

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# Restart your shell for the changes to take effect.

You can manually add the above lines to the appropriate file, then restart your terminal for the changes to take effect.

Usage

Installing a specific version

List all available Python versions:

pyenv install -l

Install a specific version:

For example, Python 3.13.5

pyenv install -v 3.13.5

Check installed versions:

pyenv versions

Applying a version

When multiple version settings exist, the priority order is:

1. shell
2. local
3. global

Set the version for the current shell session:

pyenv shell 3.13.5

Set the version for the current project directory:

pyenv local 3.13.5

Set a global (default) version:

pyenv global 3.13.5

Verify the active version:

python3 --version

Reverting to the system Python

pyenv global system

If this doesn’t take effect, try removing the following file: /Users/{user_name}/.pyenv/version.