Installing Python "The Right Way" on a MacBook for Beginners (2024 Edition)
Learn how to install and manage multiple Python versions on your MacBook using PyEnv and PyEnv Virtualenv.
Can You Relate?
๐ You are facing frustrations with version conflicts between different projects requiring specific Python versions?
๐ You are concerned about environment pollution caused by globally installing various packages?
๐ You are struggling to replicate your development environment on another machine due to dependency issues?
๐ You are worried about the risk of breaking your system during package installation or uninstallation?
If you answered yes to any of these, this guide is here to help!
Let's Begin!
Pre Requisites
MacBook
Homebrew Installation
Step 1: Installing Homebrew (if not already installed)
Before we dive into Python installation, let's install Homebrew.
It's a package manager that makes installing software on your Mac a breeze.
Open your terminal and run the following command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Step 2: Installing PyEnv
This tool helps in installing and easily switching between multiple versions of Python.
We can set Global Python version on a per-user basis.
We can set Per Project Python versions.
2a Installing PyEnv
Run brew install pyenv
to install PyEnv.
Post-installation, run pyenv --version
to confirm the installation.
Next, we need to set up our shell environment for Pyenv.
For zsh Shell, run the following commands:
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
For other shells, refer this section
2b PyEnv Useful Commands
To install a version of Python
To do that, first, we need to check all the available versions of Python via
pyenv install --list
.Run
pyenv install <version>
to install a particular version.Example
pyenv install 3.11.8
pyenv install 3.10.13
Let's install both of them
If you see below error while installing 3.11.8
Traceback (most recent call last):
File "<string>", line 1, in <module>In
File "/Users/atech-guide/.pyenv/versions/3.11.8/lib/python3.11/lzma.py", line 27, in <module>
tppl
from _lzma import *
ModuleNotFoundError: No module named '_lzma'
As solution, do the following
Install xz => brew install xz
un-install Python => pyenv uninstall 3.11.8
reinstall Python => pyenv install 3.11.8
Post successful installation, let's list the Python versions via pyenv versions
, we see the following:
atech.guide@macbook-air-m1 ~ % pyenv versions
* system (set by /Users/atech-guide/.pyenv/version)
3.10.13
3.11.8
Where system
represents the Python that comes with MacBook.
To Use a version of Python in the current Folder
Run pyenv local <version>
To set a version of Python Globally
Run pyenv global <version>
E.g. pyenv global 3.10.13
To delete a version of Python
Run pyenv uninstall <version>
E.g. pyenv uninstall 3.10.13
2c PyEnv Example
Let's create a folder named python_projects
.
Under it let's create two example projects, example_python_project_1
and example_python_project_2
.
At end, we have a folder structure as follows
atech.guide@macbook-air-m1 python_projects % tree
.
โโโ example_python_project_1
โโโ example_python_project_2
Under each project sub folder, lets use different versions of python by running
pyenv local 3.11.8
for example_python_project_1pyenv local 3.10.13
for example_python_project_2
If we check the python versions under both the sub folders (via python --version
) we will see different versions
atech.guide@macbook-air-m1 python_projects % cd example_python_project_1
atech.guide@macbook-air-m1 example_python_project_1 % pyenv local 3.11.8
atech.guide@macbook-air-m1 example_python_project_1 % python --version
Python 3.11.8
atech.guide@macbook-air-m1 example_python_project_1 % cd ../example_python_project_2
atech.guide@macbook-air-m1 example_python_project_2 % pyenv local 3.10.13
atech.guide@macbook-air-m1 example_python_project_2 % python --version
Python 3.10.13
2d PyEnv Command Table
Action | Command |
To check versions and which python is activated | pyenv versions |
To check Available versions | pyenv install --list |
To install a version | pyenv install 3.11.8 |
Where is python installed | ls ~/.pyenv/versions/ |
Uninstalling Python | pyenv uninstall 3.10.5 |
Setting Global Python | pyenv global 3.10.5 |
Setting Local Python | pyenv local 2.7.15 |
Which python is activated in pyenv | pyenv which python |
This solves one part of the problem.
Another part is we need to create Isolated Environments for each Python Project.
For that, we will need another tool.
Step 3 PyEnv Virtualenv
- It is a PyEnv plugin that provides features to manage virtualenvs for Python.
3a Installing PyEnv Virtualenv
Run brew install pyenv-virtualenv
to install PyEnv
Next, we need to set up our shell environment for Pyenv Virtualenv.
For zsh Shell, run echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshrc
.
3b PyEnv Virtualenv Useful Commands
To create a virtual env
Run pyenv virtualenv <python_version> <environment_name>
.
To use virtual env
Run pyenv local <my-virtual-env>
To List virtual env
Run pyenv virtualenvs
To delete virtual env
Run pyenv virtualenv-delete <my-virtual-env>
E.g. pyenv virtualenv-delete python_project-3.11
3c PyEnv Virtualenv Example
Before Creating Virtual environment
atech.guide@macbook-air-m1 ~ % pyenv versions
* system (set by /Users/atech-guide/.pyenv/version)
3.10.13
3.11.8
Creating a Virtual Environment -> pyenv virtualenv 3.11.8 example_python_project_1
atech.guide@macbook-air-m1 ~ % pyenv virtualenv 3.11.8 example_python_project_1
atech.guide@macbook-air-m1 ~ % pyenv versions
* system (set by /Users/atech-guide/.pyenv/version)
3.10.13
3.11.8
3.11.8/envs/example_python_project_1
example_python_project_1 --> /Users/atech-guide/.pyenv/versions/3.11.8/envs/example_python_project_1
Where 3.11.8/envs/example_python_project_1
is virtual env and example_python_project_1
is Symlink
3d PyEnv Virtualenv Command Table
Action | Command |
Create Virtual Env | pyenv virtualenv <python_version> <environment_name> |
Use Virtual env | pyenv local <environment_name> |
List virtual env | pyenv virtualenvs |
Remove Virtual env | pyenv virtualenv-delete <environment_name> |
Congratulations!
You've successfully installed and configured Python on your Mac using PyEnv and PyEnv Virtualenv.
You're now equipped to tackle Python projects with confidence, knowing you can manage versions and dependencies like a pro.
Conclusion
PyEnv and PyEnv Virtualenv are powerful tools for managing Python development environment.
Virtual environments keep our projects organized and prevent dependency conflicts.
Let me know if you'd like a follow-up article on setting up your first Python project.