Python Installation Guide

Python Installation Guide#

This guide helps you set up Python for the course. We recommend using Visual Studio Code (VS Code) with Python’s built-in virtual environment (venv) for the most consistent experience across all platforms.

Before you start: You’ll need to use a terminal (also called command line or command prompt). This is a text-based way to give commands to your computer. Don’t worry if you’ve never used one before - we’ll guide you through it!

Choose your operating system below for specific instructions:

Linux#

1. Install Python 3.12#

Most Linux distributions come with Python pre-installed. Check your version:

Open a terminal (search for “Terminal” in your applications) and type:

python3 --version

If you need Python 3.12 specifically, install it using your package manager:

Ubuntu/Debian:

sudo apt update
sudo apt install python3.12 python3.12-venv

Fedora/CentOS/RHEL:

sudo dnf install python3.12

Arch Linux:

sudo pacman -S python

Alternative: Conda/Mamba#

If you prefer conda or need it for complex dependencies:

# Install miniconda
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

# Create environment
conda create -n messfern_env python=3.12
conda activate messfern_env

# Install packages
pip install -r requirements.txt

Windows#

1. Install Python 3.12#

  1. Download Python 3.12 from: https://www.python.org/downloads/

  2. Important: During installation, check “Add Python to PATH” (this lets you run Python from anywhere on your computer)

  3. Important: Check “Install pip” and “Install py launcher”

Verify installation: Open Command Prompt or PowerShell (search for it in Start menu) and type:

python --version

You should see “Python 3.12.x” displayed.

2. Set up VS Code + venv (Recommended)#

  1. Install VS Code:

    • Download from: https://code.visualstudio.com/

    • Run the installer and follow the setup wizard

    • Install the Python extension: Open VS Code, click the Extensions icon (looks like 4 squares) on the left sidebar, search for “Python”, and click Install on the Microsoft Python extension

  2. Create a project folder and virtual environment:

    Open PowerShell or Command Prompt and type:

    mkdir $HOME\messfern  # Creates a folder called 'messfern' in your user folder
cd $HOME\messfern     # Goes into that folder
python -m venv .venv  # Creates a virtual environment

  3. Activate the environment:

    In PowerShell (still in the messfern folder):

    .\.venv\Scripts\Activate.ps1

    You’ll see (.venv) appear at the beginning of your prompt when it’s activated.

  4. Install required packages:

    First, download this simple requirements.txt file to test your setup: Download requirements.txt (right-click and “Save As…” to your messfern folder)

    In PowerShell (with venv activated):

    pip install --upgrade pip
pip install -r requirements.txt

  5. Set up VS Code:

    • Open the messfern folder in VS Code (File → Open Folder)

    • When prompted to select a Python interpreter, click the version shown in the bottom-left corner and choose the .venv option

    • Install the Jupyter extension: Extensions sidebar → search “Jupyter” → install the Microsoft Jupyter extension

Alternative: Conda/Mamba#

If you prefer conda or need it for complex dependencies:

# Install miniconda (download and run installer from https://docs.conda.io/en/latest/miniconda.html)
# Then create environment
conda create -n messfern_env python=3.12
conda activate messfern_env

# Install packages
pip install -r requirements.txt

macOS#

1. Install Python 3.12#

macOS comes with Python pre-installed, but we recommend installing Python 3.12:

  1. Install Homebrew (if not already installed):

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Install Python 3.12:

    brew install python@3.12

Verify installation: Open the macOS Terminal app (search for “Terminal” in Spotlight - this is the built-in terminal, not VS Code) and type:

python3.12 --version

2. Set up VS Code + venv (Recommended)#

  1. Install VS Code:

    • Download from: https://code.visualstudio.com/

    • Open the downloaded file and drag VS Code to your Applications folder

    • Install the Python extension: Open VS Code, click the Extensions icon (looks like 4 squares) on the left sidebar, search for “Python”, and click Install on the Microsoft Python extension

  2. Create a project folder and virtual environment:

    Open the macOS Terminal app and type:

    mkdir -p ~/messfern  # Creates a folder called 'messfern' in your home directory
cd ~/messfern        # Goes into that folder
python3.12 -m venv .venv  # Creates a virtual environment

  3. Activate the environment:

    In the macOS Terminal app (still in the messfern folder):

    source .venv/bin/activate

    You’ll see (.venv) appear at the beginning of your terminal prompt when it’s activated.

  4. Install required packages:

    First, download this simple requirements.txt file to test your setup: Download requirements.txt (right-click and “Save As…” to your messfern folder)

    In the macOS Terminal app (with .venv activated):

    pip install --upgrade pip
pip install -r requirements.txt

  5. Set up VS Code:

    • Open the ~/messfern folder in VS Code (File → Open Folder)

    • When prompted to select a Python interpreter, click the version shown in the bottom-left corner and choose the .venv option

    • Install the Jupyter extension: Extensions sidebar → search “Jupyter” → install the Microsoft Jupyter extension

Alternative: Conda/Mamba#

If you prefer conda or need it for complex dependencies:

# Install miniconda
brew install miniconda
conda init zsh  # or bash

# Create environment
conda create -n messfern_env python=3.12
conda activate messfern_env

# Install packages
pip install -r requirements.txt

Common Issues & Troubleshooting#

Package Installation Issues#

Some packages like cartopy and netCDF4 require system libraries. If installation fails:

  • Linux: Install system dependencies first:

    sudo apt install libgeos-dev libproj-dev libnetcdf-dev  # Ubuntu/Debian

  • macOS: Use conda instead:

    conda install -c conda-forge cartopy netCDF4

  • Windows: Use conda instead:

    conda install -c conda-forge cartopy netCDF4

VS Code Doesn’t See Your Environment#

If VS Code doesn’t detect your virtual environment:

In your terminal (with venv activated):

# Install ipykernel
pip install ipykernel
python -m ipykernel install --user --name=.venv --display-name "Python (.venv)"

Then restart VS Code and select the kernel.

GitHub Codespaces (No Local Installation Required)#

If you have trouble with local Python setup or prefer a cloud-based solution, GitHub Codespaces provides a complete Python environment in your browser.

Setting Up Codespaces for Assignments#

  1. Accept your GitHub Classroom assignment (click the link from your instructor)

  2. Go to your assignment repository

  3. Click the green “Code” button

  4. Go to the “Codespaces” tab

  5. Click “Create codespace on main”

  6. In the setup screen:

    • Machine type: 2-core (default is fine)

    • Dev container: Choose “Python 3.11” (NOT Python 3.14 or newer versions)

    • ✅ Tick the checkbox for “Install requirements.txt dependencies”

  7. Click “Create codespace”

⏰ Important: The first time setup will take 5-10 minutes. This is normal! The system is installing all oceanographic packages (matplotlib, xarray, cartopy, etc.).

Working in Codespaces#

  • Jupyter notebooks: If a notebook shows raw JSON instead of cells, right-click the .ipynb file and select “Open With → Jupyter”

  • Terminal access: Use the integrated terminal for git commands and running tests

  • File editing: Full VS Code editor with Python and Jupyter extensions pre-installed

  • Automatic saves: Your work is automatically saved to your GitHub repository

Codespaces vs Local Development#

Choose Codespaces if:

  • You have installation issues with Python packages

  • You’re using a Chromebook or tablet

  • You want zero-setup convenience

  • You prefer not to install development tools locally

Choose Local Python if:

  • You want to work offline

  • You prefer having full control over your environment

  • You already have Python set up

  • You want faster performance for large datasets

GitHub Classroom Assignments (Local Setup)#

If you prefer local development:

  • Click the assignment link from your instructor (this creates a private copy of the assignment for you)

  • Click the green “Accept this assignment” button

  • Follow the instructions to create/link your GitHub account if needed

  • Click “Go to repository” to see your personal assignment repository

  • Clone the repository:

    1. On your assignment repository page, click the green “Code” button

    2. Copy the entire URL (for example, if your username is “eleanorfrajka”, it would be https://github.com/ifmeo-courses/exercise-1-ctd-eleanorfrajka)

    3. Run this in your terminal, replacing the URL with what you copied:

    git clone https://github.com/ifmeo-courses/assignment-name-your-username.git
cd assignment-name-your-username

# Example for username "eleanorfrajka":
git clone https://github.com/ifmeo-courses/exercise-1-ctd-eleanorfrajka.git
cd exercise-1-ctd-eleanorfrajka

  • The requirements.txt will be at the repository root - follow the setup instructions above using that file

Contents