Setting Up Your Environment

Published

Mar 2026

  • ID: DS-L01
  • Type: Foundation
  • Audience: Beginner / Intermediate
  • Theme: Reproducibility starts before analysis

This guide is Python-first and Quarto-first.

In CDI, environment setup is not a technical formality — it is part of the analytical process.

If your environment is inconsistent, your results can be:

You will write and run code inside Quarto chapter files (.qmd). When you render the book, Quarto executes Python chunks and embeds results directly into the final output.

What you are setting up

By the end of this lesson you will have:

  • Python installed and accessible from the terminal
  • A project virtual environment (.venv)
  • Required packages installed
  • Quarto installed and working
  • A working build pipeline that renders into docs/

Required software

Python (3.10 or newer)

Check if Python is available:

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

If this fails, install Python:

  • macOS: brew install python
  • Windows: Install from python.org (enable “Add to PATH”)
  • Linux: Use your package manager (apt, dnf, pacman)

Quarto

Quarto renders the book and executes code.

Check installation:

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

If missing, install from https://quarto.org and confirm the version prints.

Project environment

This project uses a local virtual environment to ensure reproducibility.

Use the setup script

From the project root:

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

Activate the environment:

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

Verify:

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

The path should point to .venv.

If you are on Windows:

  • 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

CDI workflow primarily uses Quarto rendering, not notebooks.

Render the book

With the environment active:

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

This runs quarto render and outputs to docs/.

Sanity check (critical step)

Open the generated site.

macOS

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

Linux

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

Windows

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

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

Development mode (optional)

#| label: 01-preview-book
quarto preview

This launches a live server that reloads on changes.

CDI Insight

Environment setup is the first step in reproducibility.

Before analyzing data, you must ensure:

  • your tools are consistent
  • your dependencies are controlled
  • your workflow is repeatable

This is what allows your results to be trusted.

Summary

  • Python and Quarto are installed
  • A reproducible .venv environment is created
  • The Quarto book builds successfully
  • You are ready to start working with data

Next Step

→ Load and explore your first dataset