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

1. To do that, first, we need to check all the available versions of Python via pyenv install --list.

2. Run pyenv install <version> to install a particular version.

3. Example

   1. pyenv install 3.11.8

   2. 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_1

• pyenv 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

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

---

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.

References

• Homebrew

• PyEnv GitHub

• PyEnv pyenv-virtualenv GitHub

• Python 3.11.8 installation error solution Gist

• Image Credit: Google Gemini