Environments and Dependencies

projects-and-environments

Use virtual environments, install packages, and understand pyproject.toml.

Level: Beginner to intermediate
Estimated time: 35–50 minutes
You will learn: Use virtual environments, install packages, and understand pyproject.toml.
Practice in: VS Code and the terminal

Open this lesson in Google Colab

Questions

What problem does Environments and Dependencies help us solve in a small Python program?
What should we predict before running the example?
What value, output, or error should we inspect after changing one line?

Objectives

Run a complete example for environments and dependencies in Colab.
Explain the example line by line using plain language.
Change one part of the code and predict the result before running it.
Recognize one common mistake and use the error message as evidence.

Hands-on episode: Environments and Dependencies

A dependency is external code your project needs. An environment is the Python interpreter plus installed packages used for one project.

We will learn this by running code, not by memorizing a definition first. Open the Colab notebook from the button above, find this section, and run each cell in order. Keep a small note beside the notebook with three columns: prediction, actual result, and what changed.

Example 1.1

Read these commands as a reproducible setup story, not as magic terminal incantations.

python -m venv .venv
python -m pip install pandas
python -m pip freeze > requirements.txt

Run the cell once without editing it. If the result is different from your prediction, leave the prediction visible and write one sentence about the difference. That sentence is more useful than a perfect first guess.

Explain Example 1.1

The first command creates a local environment folder for this project.
The second command installs a package using the selected Python interpreter.
The third command records installed package versions so another person can recreate the setup.

Now explain the example out loud or in a Markdown cell. Use short sentences: “this line creates…”, “this name stores…”, “this output appears because…”. If you cannot explain a line yet, run only the lines above it and inspect the values that exist at that moment.

Challenge 1.1

Challenge

After installing a package, run python -c "import pandas; print(pandas.__version__)". This verifies that the same interpreter can import the package.

Show a safe way to approach the challenge

Copy Example 1.1 into a new Colab cell.
Change exactly one value, name, condition, or line.
Write the expected output before running the cell.
Run the cell and compare the actual result with your prediction.
If the result surprises you, undo the change and try a smaller one.

Suggested first move: After installing a package, run python -c "import pandas; print(pandas.__version__)".

Debugging checkpoint 1.1

Debugging checkpoint

The most common environment bug is using one Python to install and another Python to run. Always check the interpreter path in VS Code, Jupyter, and the terminal. Recording dependencies is part of the project, not an optional cleanup step.

Do not debug by rewriting the whole example. Read the error type or surprising output, inspect the closest value with print(...) or type(...), then change one thing. This is the same routine you will use in larger projects.

Apply it

Create a tiny environment, install one library, verify the import, record dependencies, and write down the exact commands another learner would need to repeat your setup.

Finish by adding a Markdown cell that answers: What did this example teach me that I can reuse in a project?

Key points

Learn the concept by running a complete, small example first.
Predict before execution so your thinking becomes visible.
Change one thing at a time so cause and effect stay clear.
Treat errors as clues about the exact line or value Python could not handle.

Why this matters

Use virtual environments, install packages, and understand pyproject.toml.

This lesson combines related subtopics that belong together in one learning conversation. You will still pause for a quiz after each section, but you do not need to jump between separate pages while building one clear explanation.

Guiding questions

By the end of this lesson, you should be able to answer:

How do the sections in Environments and Dependencies fit together?
Which small example demonstrates each section?
Which debugging clue should I check first for each section?

Learning objectives

You will practice how to:

explain the shared concept for this lesson;
use each section as one step in a larger workflow;
complete 3 short section quizzes before moving on;
connect examples, mistakes, and debugging routines.

Lesson map

1. Virtual Environments — Create isolated Python environments for project dependencies.
2. Installing Packages — Install third-party libraries and record what your project needs.
3. pyproject.toml — Understand the configuration file used by modern Python projects.

How environments connect tools and packages

A virtual environment keeps one project’s interpreter and installed packages separate from other projects.

flowchart TD
  project["project folder"] --> venv[".venv<br/>virtual environment"]
  venv --> python["Python interpreter"]
  venv --> packages["installed packages<br/>numpy, pandas, pytest"]
  project --> pyproject["pyproject.toml<br/>dependency list"]
  system["system Python"] -. separate from .-> venv

When imports fail, check which Python interpreter is active before reinstalling packages.

1. Virtual Environments

Create isolated Python environments for project dependencies.

Analogy

A virtual environment is a separate lunchbox: one project’s ingredients do not spill into another’s.

What this means

A virtual environment gives one project its own installed packages.

Example 1

Predict what will happen before you run the code.

python -m venv .venv
source .venv/bin/activate
python -m pip install requests

Step-by-step explanation

python -m venv .venv — pause here and say what this line reads, creates, changes, or displays.
source .venv/bin/activate — pause here and say what this line reads, creates, changes, or displays.
python -m pip install requests — pause here and say what this line reads, creates, changes, or displays.

After running the example, compare the actual output with your prediction. If they differ, do not erase your prediction. The difference is the part that can teach you the most.

Challenge

Practice

Change one input value, predict the new output, run the code, and explain the difference in one sentence.

Show one possible solution path

Copy Example 1 into Colab, Jupyter, or a .py file.
Mark the line you plan to change.
Write a one-sentence prediction.
Run the changed code.
If the result surprises you, restore the original and change a smaller part.

The goal is not to find the only correct answer. The goal is to create a small experiment where you can explain cause and effect.

Common mistakes

Common mistake

Installing packages before activating the environment often installs them in the wrong place. Check which python.

When you get stuck, use this debugging routine:

Read the last line of the error message or inspect the unexpected output.
Find the smallest line of code that could be responsible.
Print or inspect the value and type at that point.
Change one thing.
Run again and record what changed.

Check your understanding

This quiz checks the ideas in this section before you move on.

{
  const scripts = Array.from(
    document.querySelectorAll("script.fcpython-ojs-quiz-config")
  );
  const script = scripts.find(
    (node) => node.dataset.fcpythonRendered !== "true"
  );

  if (!script) {
    return html`<div class="fcpython-quiz fcpython-quiz-warning">
      Quiz configuration was not found.
    </div>`;
  }

  script.dataset.fcpythonRendered = "true";
  const quiz = JSON.parse(script.textContent);
  const container = html`<div class="fcpython-quiz"></div>`;
  const title = document.createElement("h3");
  title.textContent = quiz.title;
  container.appendChild(title);

  const instructions = document.createElement("p");
  instructions.textContent = quiz.instructions;
  container.appendChild(instructions);

  const feedbackNodes = [];

  quiz.questions.forEach((question, questionIndex) => {
    const fieldset = document.createElement("fieldset");
    fieldset.className = "fcpython-quiz-question";

    const legend = document.createElement("legend");
    legend.textContent = `${questionIndex + 1}. ${question.prompt}`;
    fieldset.appendChild(legend);

    question.options.forEach((option, optionIndex) => {
      const label = document.createElement("label");
      label.className = "fcpython-quiz-option";

      const input = document.createElement("input");
      input.type = "radio";
      input.name = `${quiz.id}-${question.id}`;
      input.value = String(optionIndex);

      const text = document.createElement("span");
      text.textContent = option;

      label.appendChild(input);
      label.appendChild(text);
      fieldset.appendChild(label);
    });

    const feedback = document.createElement("p");
    feedback.className = "fcpython-quiz-feedback";
    feedback.setAttribute("aria-live", "polite");
    feedbackNodes.push(feedback);
    fieldset.appendChild(feedback);
    container.appendChild(fieldset);
  });

  const actions = document.createElement("div");
  actions.className = "fcpython-quiz-actions";

  const check = document.createElement("button");
  check.type = "button";
  check.textContent = "Check answers";

  const reset = document.createElement("button");
  reset.type = "button";
  reset.textContent = "Reset";

  const score = document.createElement("p");
  score.className = "fcpython-quiz-score";
  score.setAttribute("aria-live", "polite");

  check.addEventListener("click", () => {
    let correctCount = 0;

    quiz.questions.forEach((question, questionIndex) => {
      const selected = container.querySelector(
        `input[name="${quiz.id}-${question.id}"]:checked`
      );
      const feedback = feedbackNodes[questionIndex];

      if (!selected) {
        feedback.textContent = "Choose an answer before checking.";
        feedback.className = "fcpython-quiz-feedback";
        return;
      }

      const selectedIndex = Number(selected.value);
      if (selectedIndex === question.answer_index) {
        correctCount += 1;
        feedback.textContent = `✅ Correct. ${question.explanation}`;
        feedback.className = "fcpython-quiz-feedback is-correct";
      } else {
        const answer = question.options[question.answer_index];
        feedback.textContent = `❌ Not yet. Correct answer: ${answer}. ${question.explanation}`;
        feedback.className = "fcpython-quiz-feedback is-incorrect";
      }
    });

    score.textContent = `Score: ${correctCount}/${quiz.questions.length}`;
  });

  reset.addEventListener("click", () => {
    container.querySelectorAll("input[type='radio']").forEach((input) => {
      input.checked = false;
    });
    feedbackNodes.forEach((feedback) => {
      feedback.textContent = "";
      feedback.className = "fcpython-quiz-feedback";
    });
    score.textContent = "";
  });

  actions.appendChild(check);
  actions.appendChild(reset);
  container.appendChild(actions);
  container.appendChild(score);
  return container;
}

2. Installing Packages

Install third-party libraries and record what your project needs.

Analogy

Installing a package is borrowing a specialized tool from a community workshop.

What this means

Packages extend Python with code written by other people.

Example 2

Predict what will happen before you run the code.

python -m pip install numpy
python -m pip show numpy

Step-by-step explanation

python -m pip install numpy — pause here and say what this line reads, creates, changes, or displays.
python -m pip show numpy — pause here and say what this line reads, creates, changes, or displays.

After running the example, compare the actual output with your prediction. If they differ, do not erase your prediction. The difference is the part that can teach you the most.

Challenge

Practice

Change one input value, predict the new output, run the code, and explain the difference in one sentence.

Show one possible solution path

Copy Example 1 into Colab, Jupyter, or a .py file.
Mark the line you plan to change.
Write a one-sentence prediction.
Run the changed code.
If the result surprises you, restore the original and change a smaller part.

The goal is not to find the only correct answer. The goal is to create a small experiment where you can explain cause and effect.

Common mistakes

Common mistake

Use python -m pip so pip belongs to the Python interpreter you are using.

When you get stuck, use this debugging routine:

Read the last line of the error message or inspect the unexpected output.
Find the smallest line of code that could be responsible.
Print or inspect the value and type at that point.
Change one thing.
Run again and record what changed.

Check your understanding

This quiz checks the ideas in this section before you move on.

{
  const scripts = Array.from(
    document.querySelectorAll("script.fcpython-ojs-quiz-config")
  );
  const script = scripts.find(
    (node) => node.dataset.fcpythonRendered !== "true"
  );

  if (!script) {
    return html`<div class="fcpython-quiz fcpython-quiz-warning">
      Quiz configuration was not found.
    </div>`;
  }

  script.dataset.fcpythonRendered = "true";
  const quiz = JSON.parse(script.textContent);
  const container = html`<div class="fcpython-quiz"></div>`;
  const title = document.createElement("h3");
  title.textContent = quiz.title;
  container.appendChild(title);

  const instructions = document.createElement("p");
  instructions.textContent = quiz.instructions;
  container.appendChild(instructions);

  const feedbackNodes = [];

  quiz.questions.forEach((question, questionIndex) => {
    const fieldset = document.createElement("fieldset");
    fieldset.className = "fcpython-quiz-question";

    const legend = document.createElement("legend");
    legend.textContent = `${questionIndex + 1}. ${question.prompt}`;
    fieldset.appendChild(legend);

    question.options.forEach((option, optionIndex) => {
      const label = document.createElement("label");
      label.className = "fcpython-quiz-option";

      const input = document.createElement("input");
      input.type = "radio";
      input.name = `${quiz.id}-${question.id}`;
      input.value = String(optionIndex);

      const text = document.createElement("span");
      text.textContent = option;

      label.appendChild(input);
      label.appendChild(text);
      fieldset.appendChild(label);
    });

    const feedback = document.createElement("p");
    feedback.className = "fcpython-quiz-feedback";
    feedback.setAttribute("aria-live", "polite");
    feedbackNodes.push(feedback);
    fieldset.appendChild(feedback);
    container.appendChild(fieldset);
  });

  const actions = document.createElement("div");
  actions.className = "fcpython-quiz-actions";

  const check = document.createElement("button");
  check.type = "button";
  check.textContent = "Check answers";

  const reset = document.createElement("button");
  reset.type = "button";
  reset.textContent = "Reset";

  const score = document.createElement("p");
  score.className = "fcpython-quiz-score";
  score.setAttribute("aria-live", "polite");

  check.addEventListener("click", () => {
    let correctCount = 0;

    quiz.questions.forEach((question, questionIndex) => {
      const selected = container.querySelector(
        `input[name="${quiz.id}-${question.id}"]:checked`
      );
      const feedback = feedbackNodes[questionIndex];

      if (!selected) {
        feedback.textContent = "Choose an answer before checking.";
        feedback.className = "fcpython-quiz-feedback";
        return;
      }

      const selectedIndex = Number(selected.value);
      if (selectedIndex === question.answer_index) {
        correctCount += 1;
        feedback.textContent = `✅ Correct. ${question.explanation}`;
        feedback.className = "fcpython-quiz-feedback is-correct";
      } else {
        const answer = question.options[question.answer_index];
        feedback.textContent = `❌ Not yet. Correct answer: ${answer}. ${question.explanation}`;
        feedback.className = "fcpython-quiz-feedback is-incorrect";
      }
    });

    score.textContent = `Score: ${correctCount}/${quiz.questions.length}`;
  });

  reset.addEventListener("click", () => {
    container.querySelectorAll("input[type='radio']").forEach((input) => {
      input.checked = false;
    });
    feedbackNodes.forEach((feedback) => {
      feedback.textContent = "";
      feedback.className = "fcpython-quiz-feedback";
    });
    score.textContent = "";
  });

  actions.appendChild(check);
  actions.appendChild(reset);
  container.appendChild(actions);
  container.appendChild(score);
  return container;
}

3. pyproject.toml

Understand the configuration file used by modern Python projects.

Analogy

pyproject.toml is a project recipe card: name, ingredients, tools, and rules in one place.

What this means

pyproject.toml records project metadata, dependencies, and tool configuration.

Example 3

Predict what will happen before you run the code.

[project]
name = "my-project"
version = "0.1.0"
dependencies = ["numpy"]

Step-by-step explanation

[project] — pause here and say what this line reads, creates, changes, or displays.
name = "my-project" — pause here and say what this line reads, creates, changes, or displays.
version = "0.1.0" — pause here and say what this line reads, creates, changes, or displays.
dependencies = ["numpy"] — pause here and say what this line reads, creates, changes, or displays.

After running the example, compare the actual output with your prediction. If they differ, do not erase your prediction. The difference is the part that can teach you the most.

Challenge

Practice

Change one input value, predict the new output, run the code, and explain the difference in one sentence.

Show one possible solution path

Copy Example 1 into Colab, Jupyter, or a .py file.
Mark the line you plan to change.
Write a one-sentence prediction.
Run the changed code.
If the result surprises you, restore the original and change a smaller part.

The goal is not to find the only correct answer. The goal is to create a small experiment where you can explain cause and effect.

Common mistakes

Common mistake

Configuration files are read by tools. A typo may not fail until that tool runs.

When you get stuck, use this debugging routine:

Read the last line of the error message or inspect the unexpected output.
Find the smallest line of code that could be responsible.
Print or inspect the value and type at that point.
Change one thing.
Run again and record what changed.

Check your understanding

This quiz checks the ideas in this section before you move on.

{
  const scripts = Array.from(
    document.querySelectorAll("script.fcpython-ojs-quiz-config")
  );
  const script = scripts.find(
    (node) => node.dataset.fcpythonRendered !== "true"
  );

  if (!script) {
    return html`<div class="fcpython-quiz fcpython-quiz-warning">
      Quiz configuration was not found.
    </div>`;
  }

  script.dataset.fcpythonRendered = "true";
  const quiz = JSON.parse(script.textContent);
  const container = html`<div class="fcpython-quiz"></div>`;
  const title = document.createElement("h3");
  title.textContent = quiz.title;
  container.appendChild(title);

  const instructions = document.createElement("p");
  instructions.textContent = quiz.instructions;
  container.appendChild(instructions);

  const feedbackNodes = [];

  quiz.questions.forEach((question, questionIndex) => {
    const fieldset = document.createElement("fieldset");
    fieldset.className = "fcpython-quiz-question";

    const legend = document.createElement("legend");
    legend.textContent = `${questionIndex + 1}. ${question.prompt}`;
    fieldset.appendChild(legend);

    question.options.forEach((option, optionIndex) => {
      const label = document.createElement("label");
      label.className = "fcpython-quiz-option";

      const input = document.createElement("input");
      input.type = "radio";
      input.name = `${quiz.id}-${question.id}`;
      input.value = String(optionIndex);

      const text = document.createElement("span");
      text.textContent = option;

      label.appendChild(input);
      label.appendChild(text);
      fieldset.appendChild(label);
    });

    const feedback = document.createElement("p");
    feedback.className = "fcpython-quiz-feedback";
    feedback.setAttribute("aria-live", "polite");
    feedbackNodes.push(feedback);
    fieldset.appendChild(feedback);
    container.appendChild(fieldset);
  });

  const actions = document.createElement("div");
  actions.className = "fcpython-quiz-actions";

  const check = document.createElement("button");
  check.type = "button";
  check.textContent = "Check answers";

  const reset = document.createElement("button");
  reset.type = "button";
  reset.textContent = "Reset";

  const score = document.createElement("p");
  score.className = "fcpython-quiz-score";
  score.setAttribute("aria-live", "polite");

  check.addEventListener("click", () => {
    let correctCount = 0;

    quiz.questions.forEach((question, questionIndex) => {
      const selected = container.querySelector(
        `input[name="${quiz.id}-${question.id}"]:checked`
      );
      const feedback = feedbackNodes[questionIndex];

      if (!selected) {
        feedback.textContent = "Choose an answer before checking.";
        feedback.className = "fcpython-quiz-feedback";
        return;
      }

      const selectedIndex = Number(selected.value);
      if (selectedIndex === question.answer_index) {
        correctCount += 1;
        feedback.textContent = `✅ Correct. ${question.explanation}`;
        feedback.className = "fcpython-quiz-feedback is-correct";
      } else {
        const answer = question.options[question.answer_index];
        feedback.textContent = `❌ Not yet. Correct answer: ${answer}. ${question.explanation}`;
        feedback.className = "fcpython-quiz-feedback is-incorrect";
      }
    });

    score.textContent = `Score: ${correctCount}/${quiz.questions.length}`;
  });

  reset.addEventListener("click", () => {
    container.querySelectorAll("input[type='radio']").forEach((input) => {
      input.checked = false;
    });
    feedbackNodes.forEach((feedback) => {
      feedback.textContent = "";
      feedback.className = "fcpython-quiz-feedback";
    });
    score.textContent = "";
  });

  actions.appendChild(check);
  actions.appendChild(reset);
  container.appendChild(actions);
  container.appendChild(score);
  return container;
}

Notebook and Colab practice

Open a blank notebook at https://colab.new. Use one section at a time: copy the Example 1, predict the result, run it, answer the section quiz, and then move to the next section. This is better than copying the entire page at once.

Instructor note

Teaching notes

Treat each section as a short teaching episode.
Pause for the section quiz before introducing the next section.
Ask learners to compare sections: what stayed the same, and what changed?
If time is short, teach the first two sections live and assign the rest as practice.

Key points

Virtual Environments: A virtual environment gives one project its own installed packages.
Installing Packages: Packages extend Python with code written by other people.
pyproject.toml: pyproject.toml records project metadata, dependencies, and tool configuration.
Use the section quizzes as gates: review before moving on if a quiz feels uncertain.

References

Python modules tutorial: https://docs.python.org/3/tutorial/modules.html
venv documentation: https://docs.python.org/3/library/venv.html
argparse documentation: https://docs.python.org/3/library/argparse.html
Python Tutorial: https://docs.python.org/3/tutorial/
Quarto OJS documentation: https://quarto.org/docs/interactive/ojs/
ipywidgets documentation: https://ipywidgets.readthedocs.io/en/stable/