Module 2b: Installing and Using uv

Your Modern Python Setup¶

Time required: 20-30 minutes
Prerequisites: Module 2a (understanding environments)
What you’ll do: Install uv, create your first project, and run Python code

What We’ll Accomplish¶

By the end of this module, you’ll have:

✅ uv installed on your computer
✅ Your first Python project created
✅ Scientific packages installed (pandas, numpy, matplotlib)
✅ A working test script that creates a plot

This is the last setup module—after this, you’ll start writing real water modelling code!

Step 1: Install uv¶

uv is a fast, modern Python package manager. Follow the official installation guide for your operating system:

uv Installation Guide

The official guide includes:

• Installation commands for Windows, macOS, and Linux

• Alternative installation methods (pip, Homebrew, etc.)

• Troubleshooting for common issues

After Installation¶

Important: Close your terminal and open a new one. This ensures the uv command is available.

Verify Installation¶

In your new terminal, type:

uv --version

You should see a version number like uv 0.5.6 (your version may be different). As long as you see a version, uv is installed.

Tip: If you see “command not found” or “not recognized”, try closing ALL terminal windows and opening a fresh one. If that doesn’t work, see the official troubleshooting guide.

Step 2: Create Your First Project¶

Now let’s create a folder for your water modelling work.

Navigate to Your Documents Folder¶

In your terminal:

Windows:

cd ~\Documents

macOS / Linux:

cd ~/Documents

Note: You can put your project anywhere you like. Documents is just a sensible default.

Create and Initialize the Project¶

uv init my-water-project

You should see:

Initialized project `my-water-project` at `/Users/you/Documents/my-water-project`

Enter the Project Folder¶

cd my-water-project

What Was Created?¶

List the contents:

Windows:

dir

macOS / Linux:

ls -la

You should see:

.python-version    ← Specifies Python 3.12
pyproject.toml     ← Project configuration
hello.py           ← A sample Python file
README.md          ← Project documentation

uv has created a complete project structure for you!

Step 3: Open the Project in VS Code¶

Let’s open this project in VS Code.

Option A: From VS Code¶

1. Open VS Code

2. Go to File → Open Folder

3. Navigate to Documents/my-water-project

4. Click Select Folder (or Open on Mac)

Option B: From File Explorer / Finder¶

1. Navigate to Documents/my-water-project

2. Right-click the folder (Mac: Control-click or two-finger click on trackpad)

3. Select Open with Code (Windows) or drag the folder onto VS Code icon (Mac)

What You Should See¶

VS Code opens with your project in the Explorer sidebar:

MY-WATER-PROJECT
├── .python-version
├── hello.py
├── pyproject.toml
└── README.md

Click on hello.py to see the sample code uv created.

Step 4: Install Scientific Packages¶

Now let’s install the packages we need for water modelling:

• pandas — Data manipulation (like Excel, but better)

• numpy — Numerical calculations

• matplotlib — Creating plots

Open the Terminal in VS Code¶

In VS Code, go to View → Terminal (or press Ctrl+` — the backtick key is usually above Tab).

Make sure the terminal shows you’re in your project folder:

...\my-water-project>    (Windows)
.../my-water-project$    (Mac/Linux)

Add the Packages¶

Type this command:

uv add pandas numpy matplotlib

You’ll see uv working:

Using CPython 3.12.x
Creating virtual environment at: .venv
Resolved 12 packages in 1.23s
Prepared 12 packages in 2.45s
Installed 12 packages in 0.89s
 + matplotlib==3.8.x
 + numpy==1.26.x
 + pandas==2.1.x
 ...

Notice how fast that was! uv installed Python, created a virtual environment, and installed all packages in seconds.

What Happened?¶

Look at your project again—new items appeared:

MY-WATER-PROJECT
├── .venv/              ← NEW: Virtual environment (your isolated Python)
├── .python-version
├── hello.py
├── pyproject.toml      ← UPDATED: Now lists your dependencies
├── uv.lock             ← NEW: Exact package versions
└── README.md

Tip: The .venv folder might be hidden by default in your file browser, but it’s there! Here’s how to show hidden files:

• VS Code Explorer: Files starting with . are shown by default

• macOS Finder: Press Cmd+Shift+.

• Windows Explorer: View → Show → Hidden items

Step 5: Select the Python Interpreter in VS Code¶

VS Code needs to know which Python to use. Let’s point it to our new virtual environment.

1. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)

2. Type: Python: Select Interpreter

3. Press Enter

4. Choose the one that includes .venv in the path:

   • Windows: .venv\Scripts\python.exe

   • Mac/Linux: .venv/bin/python

Verify Selection¶

Look at the bottom-right corner of VS Code (the status bar). You should see something like:

Python 3.12.x ('.venv': venv)

This confirms VS Code is using your project’s Python environment.

Note: If you don’t see the .venv option, try closing and reopening VS Code, or click “Enter interpreter path” and navigate to the .venv folder manually.

Step 6: Create a Test Script¶

Let’s verify everything works by creating a script that uses our installed packages.

Create a New File¶

1. In VS Code, right-click in the Explorer panel (Mac: Control-click or two-finger click)

2. Select New File

3. Name it: test_setup.py

Add the Test Code¶

Copy and paste this code into test_setup.py:

"""Test script to verify Python environment is working."""

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt

print("Checking packages...")
print(f"  pandas version: {pd.__version__}")
print(f"  numpy version: {np.__version__}")
print()

# Create some sample "discharge" data
print("Creating sample discharge data...")
dates = pd.date_range('2024-01-01', periods=30, freq='D')
discharge = np.random.uniform(10, 50, 30)  # Random values between 10-50 m³/s

# Create a DataFrame (like an Excel table)
df = pd.DataFrame({
    'date': dates,
    'discharge_m3s': discharge
})

print("Sample data:")
print(df.head())
print()

# Calculate basic statistics
print("Statistics:")
print(f"  Mean discharge: {df['discharge_m3s'].mean():.2f} m³/s")
print(f"  Max discharge:  {df['discharge_m3s'].max():.2f} m³/s")
print(f"  Min discharge:  {df['discharge_m3s'].min():.2f} m³/s")
print()

# Create a simple plot
print("Creating plot...")
plt.figure(figsize=(10, 4))
plt.plot(df['date'], df['discharge_m3s'], 'b-', linewidth=1)
plt.xlabel('Date')
plt.ylabel('Discharge (m³/s)')
plt.title('Sample Hydrograph - Test Data')
plt.grid(True, alpha=0.3)
plt.tight_layout()

# Save the plot
plt.savefig('test_plot.png', dpi=150)
print("Plot saved as 'test_plot.png'")
print()
print("All tests passed! Your Python environment is ready.")

Save the file (Ctrl+S on Windows/Linux, Cmd+S on Mac).

Step 7: Run the Test Script¶

Now let’s run the script to verify everything works.

Run with uv¶

In the VS Code terminal, type:

uv run test_setup.py

Expected Output¶

You should see something like:

Checking packages...
  pandas version: 2.1.4
  numpy version: 1.26.3

Creating sample discharge data...
Sample data:
        date  discharge_m3s
0 2024-01-01      32.451234
1 2024-01-02      18.234567
2 2024-01-03      45.678901
3 2024-01-04      27.890123
4 2024-01-05      33.456789

Statistics:
  Mean discharge: 30.12 m³/s
  Max discharge:  49.87 m³/s
  Min discharge:  10.23 m³/s

Creating plot...
Plot saved as 'test_plot.png'

All tests passed! Your Python environment is ready.

Check the Plot¶

Look in the Explorer panel—you should see a new file: test_plot.png

Click on it to view your first Python-generated hydrograph!

Tip: The exact numbers will be different each time (they’re random), but the structure should be the same.

Checkpoint: Is Everything Working?¶

Let’s verify your setup is complete:

✅ uv --version shows a version number
✅ You have a my-water-project folder with .venv inside
✅ VS Code shows Python 3.12.x ('.venv') in the status bar
✅ uv run test_setup.py runs without errors
✅ test_plot.png was created

If all five are checked, congratulations! Your Python environment is ready for water modelling!

Quick Reference: Essential uv Commands¶

Here are the commands you’ll use most often:

The Key Insight¶

Always use uv run to execute Python scripts. This ensures:

• The correct Python version is used

• The correct packages are available

• You don’t need to “activate” anything

# Do this:
uv run my_analysis.py

# Not this:
python my_analysis.py  # Might use wrong Python!

Understanding Your Project Structure¶

Let’s look at what’s in your project now:

my-water-project/
├── .venv/                 ← Virtual environment (don't edit!)
│   ├── bin/ or Scripts/   ← Python executable
│   └── lib/               ← Installed packages
├── .python-version        ← Python version (3.12)
├── pyproject.toml         ← Project configuration
├── uv.lock                ← Exact package versions
├── hello.py               ← Sample file from uv init
├── test_setup.py          ← Your test script
├── test_plot.png          ← Generated plot
└── README.md              ← Project documentation

What About Version Control (Git)?

You may have heard of Git—a tool that tracks changes to your code over time, like “track changes” in Word but much more powerful. Git is essential for backing up your work, collaborating with colleagues, and reverting to previous versions if something breaks.

We don’t cover Git in this tutorial to keep things focused, but it’s an important skill to learn next. Once you’re comfortable with Python basics, check out the Git resources in Module 5.

For now: Your pyproject.toml and uv.lock files are designed to work well with Git when you’re ready!

Files You Would Keep in Git¶

When you learn Git, you’ll want to include:

• ✅ pyproject.toml — Your dependencies

• ✅ uv.lock — Exact versions for reproducibility

• ✅ .python-version — Python version

• ✅ Your .py scripts

• ✅ README.md

Files You Would Exclude from Git¶

• ❌ .venv/ — Large, can be recreated with uv sync

• ❌ __pycache__/ — Python’s cache files

• ❌ *.png, *.csv (usually) — Generated outputs

Note: When a colleague clones your project, they just run uv sync and uv recreates the exact same environment from pyproject.toml and uv.lock.

Troubleshooting¶

“uv: command not found” or “not recognized”¶

Solution:

1. Close ALL terminal windows

2. Open a completely new terminal

3. Try uv --version again

If still not working, see the official uv installation troubleshooting guide.

“No Python interpreter selected” in VS Code¶

Solution:

1. Make sure you ran uv add pandas numpy matplotlib (this creates .venv)

2. Press Ctrl+Shift+P -> “Python: Select Interpreter”

3. If .venv doesn’t appear, click “Enter interpreter path”

4. Navigate to: my-water-project/.venv/bin/python (Mac/Linux) or my-water-project\.venv\Scripts\python.exe (Windows)

“ModuleNotFoundError: No module named ‘pandas’”¶

Solution:

• Make sure you’re running with uv run script.py, not just python script.py

• Or run uv add pandas if you haven’t installed it yet

“Permission denied” errors (Mac/Linux)¶

Solution:

• Don’t use sudo with uv commands

• uv installs everything in your user directory-no admin rights needed

Plot doesn’t display / just saves to file¶

This is expected! Our script saves the plot to a file (test_plot.png) rather than displaying it in a window. This is actually better for reproducible workflows. Open the PNG file to see your plot.

VS Code terminal shows wrong directory¶

Solution:

1. Make sure you opened the folder in VS Code (File -> Open Folder)

2. Not just a single file

3. The terminal should start in your project folder

What You’ve Accomplished¶

Take a moment to appreciate what you’ve set up:

Development Environment
├── VS Code ✅
│   └── Python Extension ✅
├── uv Package Manager ✅
└── First Project ✅
    ├── Python 3.12 ✅
    ├── pandas ✅
    ├── numpy ✅
    ├── matplotlib ✅
    └── Working test script ✅

You now have a professional-grade Python development environment—the same kind of setup used by data scientists, researchers, and software engineers worldwide.

What’s Different Now¶

Summary¶

In this module, you:

✅ Installed uv on your computer
✅ Created your first Python project with uv init
✅ Installed scientific packages with uv add
✅ Connected VS Code to your project’s Python environment
✅ Ran a test script that used pandas, numpy, and matplotlib
✅ Generated your first Python plot

The Setup Is Complete!¶

You’ve finished all the installation and configuration modules. From here on, it’s all about writing Python code for water modelling.

Ready for the fun part? Continue to Module 3a: Python Basics for Water Modellers