Jun 28, 2023 4 min read Programming

Python Environment - macOS Setup Guide

Image by xkcd

This tutorial talks about setting up a macOS with pyenv + pyenv-virtualenv + pip-tools.

Why? Well, I don't consider necessary the use of pipenv, virtualenvwrapper or poetry out of the gate, since pip managed dependencies and you can automate the process using pip-tools. Also if you use pyenv-virtualenv you can create isolated pip environments so works for both personal projects or team projects. I prefer to keep it simple. One ring to rule them all.

So, this post will cover:

Setup Overview
Multiple versions of Python (pyenv)
Create Virtual Environments (pyenv-virtualenv)
Package Management (manual)
Package Management (pip-tools)

Setup Overview

Multiple versions of Python (pyenv)

This tool allows you to manage multiple versions of Python on your machine.

Installing pyenv

# Default installation path $HOME/.pyenv
> brew install pyenv

Installing Python versions

Listing all the possible version available to install in your local computer.

> pyenv install -l
Available versions:
  2.1.3
  2.2.3
  2.3.7

Installing new Python versions

> pyenv install 3.10.3
> pyenv install 3.8.3
> pyenv install 3.11.1

Show python versions in your system

> pyenv versions
3.11.1
3.10.3
3.8.3

Setting global Python version

> pyenv global 3.10.3

Create Virtual Environments (pyenv-virtualenv)

Third-party tool that allows you to create isolated Python environments. It works with both Python 2 and 3 and allows you to create virtual environments with different Python versions.

Installing pyenv-virtualenv

# Using homebrew
> brew install pyenv-virtualenv

The next commands allow pyenv to activate and deactivate environments automatically when moving directories. Add the following to your .zshrc file

> nano $HOME/.zrhrc
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
eval "$(pyenv init --path)"

Creating virtual environments

# pyenv virtualenv 3.10.3 <virtual_env_name>

# Recommended naming convention
> pyenv virtualenv 3.10.3 py3103
> pyenv virtualenv 3.8.2 py3911

# Create a virtual environment based on the global Python version
> pyenv virualenv jupylab

# Delete virtual enviorments
> pyenv uninstall my-virtual-env

# or
> pyenv virtualenv-delete my-virtual-env

Setting up your "local" version

In the directory you want to work

# Creates a .python-version file in the folder
> pyenv local py3103

# Folder version
>cat .python-version
py3103

# All versions
> pyenv versions
  system
  3.7.9
  3.7.9/envs/py379
  3.10.0
  3.10.0/envs/py3100
* 3.10.3 (set by /Users/user1/.pyenv/version)
  3.10.3/envs/jupy
  3.10.3/envs/py3103
  py379
  py3100
  py3103

After this step you can install packages manually in your project folder.

~/gitRepos/test (py3103) > pip install pandas

Package management (manual)

If you want to maintain manually your packages you can use pip.

# Create requirements.in file with dependencies
> nano requirements.in
  pandas
  pytest

Installing packages

# Pip will manage all the conflicts
pip install -r requirements.in

Create requirements.txt

pip freeze --all > requirements.txt

If you want to install more packages

> nano requirements.txt
  pandas
  pytest
  numpy

Package management (pip-tools)

A set of command line tools to help you keep your pip-based packages fresh, even when you've pinned them.

> pip install pip-tools

Create requirements.in with the packages you need

> nano requirements.in
  pandas
  pytest

Create a requirements.txt with some details, like dependencies and where they came from.

> pip-compile

# Review packages to install
> nano requirements.txt
#
# This file is autogenerated by pip-compile with Python 3.11
# by the following command:
#
#    pip-compile
#
iniconfig==2.0.0
    # via pytest
numpy==1.24.3
    # via pandas
packaging==23.1
    # via pytest
pandas==2.0.1
    # via -r requirements.in
pluggy==1.0.0
    # via pytest
pytest==7.3.1
    # via -r requirements.in
python-dateutil==2.8.2
    # via pandas
pytz==2023.3
    # via pandas
six==1.16.0
    # via python-dateutil
tzdata==2023.3
    # via pandas

To keep dependencies up to date

> pip-compile --upgrade

Install packages from requirements.txt

pip-sync

# Review the packages
> pip list
Package         Version
--------------- -------
build           0.10.0
click           8.1.3
iniconfig       2.0.0
numpy           1.24.3
packaging       23.1
pandas          2.0.1
pip             22.3.1
pip-tools       6.13.0
pluggy          1.0.0
pyproject_hooks 1.0.0
pytest          7.3.1
python-dateutil 2.8.2
pytz            2023.3
setuptools      65.5.0
six             1.16.0
tzdata          2023.3
wheel           0.40.0

For a complete explanation on what pyenv, pipenv, and virtualenv do, follow this article:

Happy coding!!!