Python Setup - Installing pyenv
Python is a programming language used for many purposes, including AI, machine learning, data analysis, and automation scripts. In 2026, many AI tools run on Python, so it is worth learning as a foundational engineering skill.
This page explains how to safely install Python with pyenv (a Python version management tool) and manage it per project.
Why Use pyenv?
Section titled “Why Use pyenv?”Why You Should Not Use the System Python
Section titled “Why You Should Not Use the System Python”macOS comes with Python already installed. This is called the “system Python.” However, it is not recommended for development.
- System Python is often required by OS tools, so modifying it can affect the OS
- It is often old, so you may not be able to use the newest features or libraries
- You cannot easily switch between different versions for different projects
Benefits of pyenv
Section titled “Benefits of pyenv”pyenv is similar to nvm for Node.js, but for Python version management.
- Multiple Python versions can coexist
- You can pin a version per project with a
.python-versionfile - You can build a development environment without affecting the system Python
Installation Steps
Section titled “Installation Steps”Step 1: Install pyenv
Section titled “Step 1: Install pyenv”Use Homebrew to install it.
brew install pyenvStep 2: Add shell configuration
Section titled “Step 2: Add shell configuration”To use pyenv from the shell, add the following lines to your config file.
For Zsh (~/.zshrc):
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"Open ~/.zshrc and add the three lines above to the end of the file.
# Open .zshrc in a text editor (nano)
nano ~/.zshrcAfter saving the file, reload the settings.
source ~/.zshrcFor Bash (~/.bashrc or ~/.bash_profile):
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"Step 3: Install Python
Section titled “Step 3: Install Python”Check the available versions and install Python.
# Show available versions (only 3.x series)
pyenv install --list | grep " 3\."
# Install Python 3.12
pyenv install 3.12.0
# Check installed versions
pyenv versionsStep 4: Set the global version
Section titled “Step 4: Set the global version”Set the default Python version for the whole computer.
pyenv global 3.12.0 # Set Python 3.12 globally
python --version # Check (example: Python 3.12.0)
pip --version # Check pipBasic pip Usage
Section titled “Basic pip Usage”pip is Python’s package manager. It is used to install libraries.
pip install requests # Install the requests library
pip install numpy pandas # Install multiple packages at once
pip list # Show installed packages
pip show requests # Show information about a specific package
pip uninstall requests # Uninstall a packageUsing Virtual Environments (venv)
Section titled “Using Virtual Environments (venv)”A virtual environment is a separate package environment for each project. It is like giving every project its own workroom. If Project A and Project B need different library versions, they will not affect each other.
Create and Activate a Virtual Environment
Section titled “Create and Activate a Virtual Environment”# Move to the project folder
cd ~/projects/my-python-app
# Create a virtual environment (.venv folder will be created)
python -m venv .venv
# Activate it on macOS / Linux
source .venv/bin/activate
# Check activation (.venv appears at the start of the prompt)
# (.venv) user@hostname my-python-app %Install Packages Inside the Virtual Environment
Section titled “Install Packages Inside the Virtual Environment”pip install requests # Installed only inside the virtual environment
pip freeze > requirements.txt # Save dependencies to a fileInstall the Same Packages in Another Environment
Section titled “Install the Same Packages in Another Environment”pip install -r requirements.txt # Install everything listed in requirements.txtDeactivate the Virtual Environment
Section titled “Deactivate the Virtual Environment”deactivate # Return to the normal Python environmentPinning a Project Version with .python-version
Section titled “Pinning a Project Version with .python-version”If you create a .python-version file in the project root, that folder will automatically use the specified version.
pyenv local 3.12.0 # Create a .python-version file
python --version # Shows 3.12.0If you commit .python-version to the repository, every team member can use the same version.
Summary
Section titled “Summary”- Do not use the system Python for development; use Python installed by pyenv
- Install pyenv with
brew install pyenvand add the settings to~/.zshrc - Install Python with
pyenv install 3.12.0and set the default withpyenv global - Create and use a virtual environment per project with
python -m venv .venv
Frequently Asked Questions
Section titled “Frequently Asked Questions”Q: python: command not found appears
A: The pyenv configuration may not have been added correctly to ~/.zshrc. Run source ~/.zshrc, then check with pyenv versions. Also confirm that the following three lines are present:
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"Q: python does not work, but python3 does
A: On macOS, python can point to Python 2 in some environments. If you set a global version with pyenv (pyenv global 3.12.0), python will use Python 3.
Q: How do I use a virtual environment in VS Code?
A: The Python extension in VS Code detects virtual environments automatically. Open the project folder in VS Code, then use the Command Palette (Cmd + Shift + P) and choose Python: Select Interpreter, then select the Python inside .venv.