How to Install pyenv on macOS

Managing multiple Python versions on macOS can be tricky—but pyenv makes it easy. This guide walks you through installing and using pyenv to streamline your Python development workflow.

Step 1: Install pyenv via Homebrew

First, install pyenv using Homebrew:

brew install pyenv

Make sure Homebrew is installed. If not, check out my How to Install Homebrew on macOS post for detailed instructions on how to install Homebrew.

Step 2: Configure Your Shell

Once installed, add the complete configuration to your shell file. First, check which shell you’re using:

echo $SHELL

Then add these lines to your shell configuration file:

• For zsh: ~/.zshrc
• For bash: ~/.bash_profile or ~/.bashrc

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

Quick way to add all lines at once (for zsh):

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

Apply the changes:

source ~/.zshrc  # or source ~/.bash_profile depending on your shell

Step 3: Install a Python Version

You can now install any version of Python you need. For example:

pyenv install 3.13.3

Step 4: Set Your Python Version

Use one of the following commands to set the desired Python version:

• Set globally:

  pyenv global 3.13.3
  

• Set locally for a project:

  pyenv local 3.13.3
  

• Set for the current shell session:

  pyenv shell 3.13.3
  

Step 5: Refresh and Verify

After setting your Python version, refresh pyenv:

pyenv rehash

Then verify the installation:

python --version

You should see the Python version you’ve set via pyenv.

Troubleshooting: “Command not found: python”

If you get zsh: command not found: python in new shells, try these fixes:

1. Verify your configuration:

cat ~/.zshrc | grep pyenv

2. Check pyenv status:

which pyenv
pyenv versions
pyenv global

3. If python command doesn’t work, try python3:

python3 --version

4. Complete reconfiguration (if needed): Re-run the configuration commands from Step 2, then:

source ~/.zshrc
pyenv rehash

5. Test in a new terminal window to ensure it works across all shells.

Conclusion

With pyenv properly configured, managing Python versions on Mac becomes simple and reliable. The key is ensuring your shell loads the pyenv configuration in every new session, which the complete setup above handles automatically.

---

Sources:

• pyenv GitHub