Skip to main content

Install pyenv on MacOs

· 6 min read
Serhii Hrekov
Serhii Hrekov
software engineer, creator, artist, programmer, projects founder

Homebrew is the recommended and easiest way to install pyenv on macOS, but you can install it without Homebrew by cloning the repository from GitHub. This method requires a few extra steps, including manually configuring your shell and installing dependencies.

1. The Git Checkout Method 💾​

This approach involves cloning the pyenv repository directly into your user's home directory.

Step 1: Clone the pyenv repository​

Open your terminal and clone the pyenv repository into the recommended default location ~/.pyenv.

git clone https://github.com/pyenv/pyenv.git ~/.pyenv

This command copies the entire pyenv source code from the official repository into a hidden folder in your home directory [3].

Step 2: Configure your shell environment​

For pyenv to work, you must add it to your system's PATH and initialize it in your shell. For modern macOS, the default shell is zsh, so you'll edit ~/.zshrc. If you use Bash, you'll need to edit ~/.bash_profile instead [4].

Add the following lines to your shell configuration file:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init --path)"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
  • export PYENV_ROOT="$HOME/.pyenv": This line sets an environment variable that tells pyenv where its files are located.
  • export PATH="$PYENV_ROOT/bin:$PATH": This line adds pyenv's bin directory to your system's PATH, making the pyenv command available in your terminal [4].
  • eval "$(pyenv init --path)" and eval "$(pyenv init -)": These commands initialize pyenv's shims and shell integration. The shims are small executable files that automatically redirect Python commands (python, pip, etc.) to the correct version managed by pyenv [4].

After adding these lines, apply the changes by reloading your shell configuration.

source ~/.zshrc

2. The Automatic Installer Method ⚙️​

The pyenv-installer is a convenient script that automates the Git checkout and shell configuration steps.

Step 1: Run the installer script​

In your terminal, run the following command to download and execute the installer script.

curl -fsSL https://pyenv.run | bash

The script will clone the pyenv repository and set up the necessary shell integrations for you [3].

Step 2: Configure your shell​

The installer will often print instructions for adding the necessary lines to your shell configuration file. You will still need to copy and paste these lines into your ~/.zshrc (or ~/.bash_profile) and then source the file.

3. Installing Python Dependencies and Troubleshooting 🛠️​

When you use pyenv install to install a Python version, it compiles Python from source. This process requires several build dependencies, such as zlib, bzip2, openssl, and readline [2]. Without Homebrew, you will need to install these manually.

The easiest way to get the core tools is by installing the Xcode Command Line Tools.

xcode-select --install
  • "Command not found": This error usually means your shell configuration was not loaded correctly. Double-check your ~/.zshrc file and ensure you have run source ~/.zshrc in your terminal.
  • "BUILD FAILED" during pyenv install: This indicates that one or more of the necessary build dependencies are missing or not correctly configured [2]. This is the most common and difficult issue when not using Homebrew, as you'll have to manually find and install the missing libraries.

Sources​

  1. Atlassian. "Resolving Conflicts During a Merge". https://www.atlassian.com/git/tutorials/using-branches/merge-conflicts
  2. GitHub. "pyenv/pyenv". https://github.com/pyenv/pyenv
  3. GitHub. "pyenv-installer". https://github.com/pyenv/pyenv-installer
  4. Mehmet Baykar. "How to Install pyenv on macOS". https://mehmetbaykar.com/posts/how-to-install-pyenv-on-macos/

This video provides a step-by-step guide to installing Pyenv and managing different Python versions on macOS, which is a great follow-up once you have Pyenv installed. Installing PyEnv on macOS - Free Full-stack Course