Skip to content
Open DegreeOpen Degree

Run a Python program and read its errors

I can run a Python program in its own virtual environment and read a traceback to name the file and line that failed, the exception type, and what the message is telling me to change.

Domain
Python Programming
Level
foundation
Status
draft · v0.1.0
Also called
Reading a traceback, Python environment setup, venv, Debugging Python
License
CC BY-SA 4.0

Learn first

Nothing. This is a starting point.

Learn it

Scope

The first twenty minutes of any Python work: an interpreter you can run, an environment that holds the right packages, and the ability to read what Python says when something breaks.

In scope: creating and activating a virtual environment, installing into it, running a script and a module, and reading a traceback. Out of scope: a debugger’s breakpoints and watch expressions, and packaging your own project, which come later.

Why the environment comes first

A Python installation is shared; a virtual environment is yours. Without one, two projects fight over the same package versions and the loser fails in a way that looks like a bug in your code. python -m venv .venv creates a directory with its own interpreter and its own site-packages, and activating it changes which python runs. Every instruction you will read from here on assumes you are inside one.

How to read a traceback

Read it bottom up. The last line is the exception type and message — the fact. Above it, the stack is the path that got there, most recent call last, each frame naming a file, a line number and the line itself.

The frame at the bottom is where Python gave up, which is not always where you went wrong: a TypeError deep inside a library usually means you passed it something wrong higher up. Walk up the frames until you reach a file you wrote. That line is where to start.

Three messages worth recognising on sight:

  • NameError: name 'x' is not defined — a typo, or use before assignment, or a variable that exists only inside another scope.
  • TypeError: ... takes 2 positional arguments but 3 were given — a call that does not match the signature, often self on a method called from the wrong place.
  • IndexError: list index out of range — an index computed from a length without accounting for zero-based counting, or an empty collection you assumed had items.

Common misconceptions

  • “The error is on the last line of the traceback.” That is where it surfaced. The cause is often in the frame above, in code you wrote.
  • “Reinstalling will fix it.” Import errors are usually the wrong environment, not a broken package. Check which python is running before touching anything.
  • “pip install installs for the project.” It installs for whichever interpreter is active. Out of a virtual environment, that is the whole machine.
  • “A stack trace means a crash.” An exception is Python telling you a rule was broken, with evidence. It is the most useful output a program produces.

Notes for teachers

Hand learners a short script that raises, rather than asking them to write one. Ask them to say aloud what the traceback claims before they touch the code — the habit of reading before editing is the whole outcome, and it transfers to every language.

A good check: break the same program in three ways and have the learner name each exception type from the message alone.

Resources

ResourceKindCostProvider
The Python Tutorial: virtual environments and packagesreadingfreePython Software Foundation
The Python Tutorial: errors and exceptionsreadingfreePython Software Foundation
CS50P, week 0: functions and variablesvideofreeHarvard University
Python Tutor, step-by-step executioninteractivefreePython Tutor

Courses that include it

draft

Python for a Coding Assessment

A refresher path through the Python graph for someone who has written Python before and has an assessment coming: run and read, rebuild the core, then work the way an assessment expects.

Prove it

Evidence of mastery

  • Creates a virtual environment, installs a package into it, and runs a script that imports that package.
  • Given a program that raises, names the failing line from the traceback and says what the exception type means, without changing code at random.
  • Distinguishes an error raised where the problem is from one raised where the problem surfaced, by reading the call stack from the bottom up.
  • Fixes a NameError, a TypeError and an IndexError in someone else's script and says what each one indicated.

Assessments that measure it

No assessment yet.

Credentials that include it

draft

Python Problem Solving

The holder can take an unfamiliar problem, write a tested Python solution someone else can run, and explain what it costs.

What learners show

Nothing to show yet. The publisher last published on 2026-09-20, and no aggregate for this outcome has reached the 50 learners a number needs. Open Degree does not track learners. About learner evidence.

What comes next