03 — Python and Conda Environment Setup

Setup
Python
Conda
Install Conda and create the course cv environment used for Python, OpenCV, PyTorch, and assignments.

Why the course uses Conda

Python projects often depend on specific versions of libraries. Installing everything into one global Python installation can cause conflicts between courses and projects.

This course uses a dedicated Conda environment named:

cv

All course Python code should be run from this environment.

Important

The exact Python, OpenCV, PyTorch, NumPy, and other package versions are defined by the official course environment files:

Use the environment file for your operating system rather than creating a separate environment with arbitrary package versions.

1. Install a Conda distribution

The recommended distribution is Miniforge, a lightweight Conda installation that uses the conda-forge package channel.

Official Miniforge repository:

https://github.com/conda-forge/miniforge

Windows users using WSL

Install Miniforge inside Ubuntu/WSL, not separately in Windows.

Open an Ubuntu terminal and check your architecture:

uname -m

Most Windows PCs will report:

x86_64

For x86-64 Linux/WSL:

curl -L -O https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh

Read the prompts carefully. Use the default installation location unless you have a specific reason to change it, and choose yes when asked whether Conda should initialize your shell.

Then reload the shell:

source ~/.bashrc

Linux

The WSL/Linux instructions above also apply to standard x86-64 Ubuntu/Linux systems.

If uname -m does not report x86_64, download the installer corresponding to your architecture from the Miniforge releases page.

macOS — Apple Silicon

Check the architecture:

uname -m

For Apple Silicon, this normally reports arm64.

Download and run:

curl -L -O https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh
bash Miniforge3-MacOSX-arm64.sh

macOS — Intel

For Intel Macs:

curl -L -O https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-x86_64.sh
bash Miniforge3-MacOSX-x86_64.sh

After installation on macOS, close and reopen Terminal or reload your shell configuration.

Native Windows alternative

Windows students are encouraged to use the WSL workflow above. If you need a native Windows Conda installation, use the Windows installer from:

https://github.com/conda-forge/miniforge/releases

Use the Miniforge Prompt for Conda commands.

Warning

Do not maintain separate Windows and WSL copies of the cv environment unless you have a specific reason to do so. If you use WSL for the course, create and use the environment inside WSL.

2. Verify Conda

Run:

conda --version

You can also list available environments:

conda env list

If you prefer not to activate Conda’s base environment every time a terminal opens:

conda config --set auto_activate_base false

Restart the terminal after changing this option.

3. Download the course environment file

The official environment files are stored in the code/ folder on the main branch of the course repository:

  • Windows/WSL and Linux: code/cv-environment.yml
  • macOS: code/cv-environment-mac.yml

The macOS environment installs PyTorch and TorchVision from conda-forge to avoid conflicts between multiple OpenMP runtimes.

Option A — Download it directly

Windows/WSL and Linux:

curl -L -o cv-environment.yml https://raw.githubusercontent.com/ariarobotics/cv/main/code/cv-environment.yml

macOS:

curl -L -o cv-environment-mac.yml https://raw.githubusercontent.com/ariarobotics/cv/main/code/cv-environment-mac.yml

Verify that the downloaded file exists:

ls -l cv-environment*.yml

Option B — Use the file from a cloned course repository

If you already cloned the course repository:

git clone https://github.com/ariarobotics/cv.git
cd cv/code

Use the environment file corresponding to your operating system.

4. Create the cv environment

From the directory containing the environment file, run the command for your operating system.

Windows/WSL and Linux:

conda env create -f cv-environment.yml

macOS:

conda env create -f cv-environment-mac.yml

Both environment files already specify the name cv, so you do not need to add -n cv.

Environment creation may take several minutes.

5. Activate the environment

Every time you work on course Python code, activate:

conda activate cv

Your terminal prompt should now begin with something similar to:

(cv)

When finished, you can deactivate it:

conda deactivate

6. Verify that you are using the correct Python

Activate the environment:

conda activate cv

Then check:

python --version

On macOS/Linux/WSL, verify the Python executable:

which python

The path should point into the cv Conda environment rather than your system Python.

You can also inspect all Conda environments:

conda env list

The active environment will have an asterisk next to it.

7. Verify the main course packages

With cv activated, run:

python -c "import numpy as np; print('NumPy:', np.__version__)"

Check OpenCV:

python -c "import cv2; print('OpenCV:', cv2.__version__)"

Check PyTorch:

python -c "import torch; print('PyTorch:', torch.__version__)"

Check TorchVision:

python -c "import torchvision; print('TorchVision:', torchvision.__version__)"

Check scikit-learn:

python -c "import sklearn; print('scikit-learn:', sklearn.__version__)"

You can test the main packages together:

python -c "import cv2, sklearn, torch, torchvision, numpy; print('OpenCV:', cv2.__version__); print('scikit-learn:', sklearn.__version__); print('PyTorch:', torch.__version__); print('TorchVision:', torchvision.__version__); print('NumPy:', numpy.__version__)"
Note

On macOS, the combined import test is especially important because it verifies that the scientific Python and PyTorch packages can load together without an OpenMP runtime conflict. Do not use KMP_DUPLICATE_LIB_OK=TRUE as a workaround.

If these commands run without import errors, the main course packages are installed correctly.

8. Confirm that Jupyter can use the environment

The course environment includes Jupyter and ipykernel.

With cv activated:

python -m ipykernel --version

You can also list available Jupyter kernels:

jupyter kernelspec list

When opening a notebook in VS Code, choose the Python kernel associated with the cv environment.

9. Updating the environment

If the course environment file changes during the semester, first download the newest copy for your operating system.

Windows/WSL and Linux:

curl -L -o cv-environment.yml https://raw.githubusercontent.com/ariarobotics/cv/main/code/cv-environment.yml
conda env update -n cv -f cv-environment.yml --prune

macOS:

curl -L -o cv-environment-mac.yml https://raw.githubusercontent.com/ariarobotics/cv/main/code/cv-environment-mac.yml
conda env update -n cv -f cv-environment-mac.yml --prune

The --prune option removes dependencies that are no longer listed in the environment definition.

After updating:

conda deactivate
conda activate cv

10. Useful Conda commands

Command Purpose
conda env list List environments
conda activate cv Activate the course environment
conda deactivate Deactivate the current environment
conda list List packages in the active environment
conda list numpy Show the installed NumPy package
conda env remove -n cv Delete the cv environment
conda clean --all Remove unused caches and downloaded packages

11. Recreating a broken environment

If the environment becomes badly inconsistent, it is often simpler to recreate it from the official course environment file.

Deactivate it:

conda deactivate

Remove it:

conda env remove -n cv

Download the current environment file if needed.

Windows/WSL and Linux:

curl -L -o cv-environment.yml https://raw.githubusercontent.com/ariarobotics/cv/main/code/cv-environment.yml
conda env create -f cv-environment.yml

macOS:

curl -L -o cv-environment-mac.yml https://raw.githubusercontent.com/ariarobotics/cv/main/code/cv-environment-mac.yml
conda env create -f cv-environment-mac.yml

12. Avoid common environment problems

Do not install course packages into base

Before running course code, verify:

conda activate cv

Do not mix Windows and WSL environments

A Python environment installed in Windows is different from one installed inside WSL. If you use WSL, install and use the cv environment inside WSL.

Be careful with manual package installation

Installing additional packages can change dependencies in the environment. If you need an extra package for a course task, use the method specified with that task.

Check the Python executable when something looks wrong

On macOS/Linux/WSL:

which python

You can also ask Python directly:

python -c "import sys; print(sys.executable)"

This often reveals that the wrong environment is active.

Next step

Once the cv environment is working, continue with the Visual Studio Code tutorial and configure VS Code to use the cv interpreter.