Installing Python, the clean way
We'll focus on pyenv for python version management. The following instructions are valid for MacOS and Linux. For Windows, please refer to the specific pyenv installation instructions.
Installing pyenv
Why install pyenv?
pyenv is a tool to manage multiple Python versions, while maintaining a consistent and clean installation process. The source code is available here.
Kind reminder: it is always a bad idea to interact with the system Python version. Python is used by most of the OS, updating some libraries (or any other operation) might break the system.
MacOS
In a terminal, run the following commands:
brew update
brew install pyenv
Linux
- ℹ️ FYI: Information about the installation available on the official Github page.
- 💡 Recommendation: Following the Berkeley tutorial
Windows
Use the pyenv-win installer. The instructions are available on Github, in the repository page.
After the OS specific installation
- A folder at root level named
.pyenvshould have been created - To refer to this folder, you can use
~/.pyenv(and you should)
Python 3.13.5 using pyenv
It is preferable to install this version, as it is important for the students to use the same version as the one used in the course, in particular, using different versions in the same course could lead to unexpected errors and issues, with the risk of being very time consuming to solve. If you are very familiar with Python installation and version management, feel free to do as you are used to.
3.13.5 is the latest stable version as of 2025/06/11. In a terminal, just run:
pyenv install 3.13.5
Nevertheless, independently of your ease with Python installation, you should use a version satisfying >=3.12, and preferably >=3.13. Not following those rules could lead to unexpected errors and issues, with the risk of being very time consuming to solve.
Virtual env setup (UNIX based OS)
We'll rely on the built-in venv module to create a virtual environment. The following instructions are valid for UNIX based OS (such as MacOS and Linux). If you use Windows, please refer to the specific instructions from the official Python documentation.
Folder creation
- Create a new folder for the virtual environment and
cdinto it. In this example, the folder is calleddataviz-course.
mkdir dataviz-course
cd dataviz-course
Creating the virtual environment
- We will create a specific virtual environment with the specified version in the
dataviz-coursefolder. - The trick is that we will use an absolute path to the python binary to create the virtual environment: therefore there cannot be any ambiguity about the interpreter used to create the virtual environment.
- The newly created environment will be called
envand created thanks to the built-invenvmodule.
This usage of absolute path is 100% consistent with The Zen of Python: In the face of ambiguity, refuse the temptation to guess.
# Creating the virtual environment
# using the absolute path to the python binary
# that we previously installed with pyenv
~/.pyenv/versions/3.13.5/bin/python -m venv env
Interacting with the virtual env
The two following commands should be run from the folder containing the virtual environment, i.e. containing the env folder.
Activating the virtual env
source env/bin/activate
Deactivating the virtual env
deactivate
Aliases & defensive programming
You should run these commands from the folder containing the virtual environment, i.e. containing the env folder, after activating the virtual environment. The goal is to ensure that the correct pip3 / pip / python3 / python are used (i.e. that the aliases are correct).
Is pip3 alias correct ?
which pip3
# path should be from the just installed and activated environment
# example: /Users/elliot/repos/dataviz-course/env/bin/pip3
Is pip alias correct ?
Also for an extra security:
which pip
# path should be from the just installed and activated environment
# example: /Users/elliot/repos/dataviz-course/env/bin/pip
Is python3 alias correct ?
Still a bit more of extra security:
which python3
# path should be from the just installed and activated environment
# example: /Users/elliot/repos/dataviz-course/env/bin/python3
Is python alias correct ?
Finally, because Defensive programming is our best friend:
which python
# path should be from the just installed and activated environment: this was the last one!
# example: /Users/elliot/repos/dataviz-course/env/bin/python
Installing JupyterLab globally
We'll install JupyterLab globally so it's available across all projects (also because it's easier to manage).
MacOS
brew install jupyterlab
Linux
Below, different instructions for different Linux distributions are listed. Using Ubuntu, we recommend to use the 2️⃣ method.
1️⃣ Using pip with the pyenv-managed Python:
~/.pyenv/versions/3.13.5/bin/pip install jupyterlab
2️⃣ Alternatively, on Ubuntu/Debian:
sudo apt update
sudo apt install python3-pip
pip3 install --user jupyterlab
3️⃣ On Fedora/RHEL/CentOS:
sudo dnf install python3-pip
pip3 install --user jupyterlab
Windows
We recommend following the instructions from the official repository. Also the official JupyterLab installation documentation for version 4.4.x is available here (last stable version as of 2024/09/15).
Register the virtual env
We need to register the virtual environment with JupyterLab to be able to use it in JupyterLab.
Ensuring we are in the correct folder
You need to access the folder containing the virtual environment, i.e. containing the env folder, after activating the virtual environment.
# Make sure to be in the folder containing the virtual environment
# by running the following command:
cd dataviz-course
Activating the virtual environment
# Make sure your virtual environment is activated
# by running the following command:
source env/bin/activate
Installing ipykernel
# Install `ipykernel`
pip3 install ipykernel==6.30.1
Registering the virtual environment with JupyterLab
# Register the environment as a kernel
python -m ipykernel install --user --name=env --display-name="dataviz-env"
After installing ipykernel in your virtual environment, register it as a kernel for JupyterLab:
Now you can start JupyterLab from anywhere and select the dataviz-env kernel to use your project's virtual environment.
# Start JupyterLab
jupyter lab
This command should also work:
jupyter-lab
Installing the libraries for the course
Make sure to be in the folder containing the virtual environment, i.e. containing the env folder, after activating the virtual environment.
# ensuring to be in the correct folder
cd dataviz-course
# activating the virtual environment
source env/bin/activate
# installing the libraries
pip3 install matplotlib==3.10.5
pip3 install ipykernel==6.30.1
pip3 install numpy==2.3.2
pip3 install pandas==2.3.2
pip3 install bokeh==3.8.0
pip3 install geopandas==1.1.1
pip3 install statsmodels==0.14.5
