Setting Up Your Environment

ID: DS-L01
Type: Lesson
Audience: Public
Theme: Project setup, Quarto workflow, and reproducible execution

This guide is Python-first and Quarto-first.

You will write and run code inside Quarto chapter files (.qmd). When you render the book, Quarto executes the Python chunks and places the results (tables, figures, printed output) directly into the published pages.

What you are setting up

By the end of this lesson you will have:

Python installed and available from the terminal
A project virtual environment (.venv) with required packages
Quarto installed for rendering the book
A working build command that generates the site into docs/

Required software

Python (3.10 or newer)

Check if Python is available:

#| label: 01-check-python
python3 --version

If that command fails, install Python using one of these options:

macOS: Homebrew brew install python
Windows: Install from python.org (ensure “Add Python to PATH” is selected)
Linux: Use your package manager (for example apt, dnf, pacman)

Quarto

Quarto renders the book and runs the Python code inside chapters.

Check if Quarto is installed:

#| label: 01-check-quarto
quarto --version

If Quarto is not installed, install it from the Quarto website and confirm the version prints successfully.

Recommended editor

Use any editor you like. A good default is VS Code because it works well with:

.qmd editing
Python formatting and linting
Git workflow

Project environment

This repo uses a local virtual environment so your package versions are isolated and reproducible.

Use the provided setup script

From the project root:

#| label: 01-setup-env-script
bash scripts/bash/setup-env.sh

Then activate the environment:

#| label: 01-activate-venv
source .venv/bin/activate

Confirm the interpreter path points to .venv:

#| label: 01-which-python
which python
python --version

If you are on Windows, activation uses a different command.

PowerShell: .venv\Scripts\Activate.ps1
cmd: .venv\Scripts\activate.bat

What the script does

Creates .venv/
Installs packages from requirements.txt
Optionally registers a Jupyter kernel named data-science

The Jupyter kernel is optional. The core workflow in this guide is Quarto rendering.

Render the book

Once the environment is active, render the book with the build script:

#| label: 01-build-book-script
bash scripts/bash/build.sh

This runs quarto render and writes the output to docs/.

Sanity check

After building the book, open the generated site.

Quick open (recommended)

macOS:

#| label: 01-open-mac
open docs/index.html

Linux:

#| label: 01-open-linux
xdg-open docs/index.html

Windows (PowerShell):

#| label: 01-open-windows
start docs/index.html

If the homepage loads and chapter navigation works, your environment is correctly configured.

Development mode (optional)

You can also run:

#| label: 01-preview-book
quarto preview

This starts a local development server and watches files for changes. It is useful when actively editing chapters because the browser reloads automatically.

The preview server runs continuously and may use a local port. For simple verification, opening docs/index.html is usually sufficient.

Summary

You confirmed Python and Quarto are installed
You created a reproducible virtual environment using .venv
You rendered the Quarto book successfully
You are ready to begin loading and exploring data