Darekdari / Python Debugging Tutorial

How to Debug Python Code in Google Colab

A practical, step-by-step guide to finding and fixing Python errors inside Google Colab — from reading tracebacks and using print() checkpoints, to driving Python’s pdb debugger, to solving the file-path, runtime, and out-of-memory problems Colab is famous for. Every example is runnable.

Python 3.10+ Google Colab pdb & IPython magics Difficulty: Beginner ~30 min read

01 / IntroductionWhy debugging in Colab is different

Google Colab gives you a free, browser-based Python environment with a GPU attached — which is why students and researchers reach for it the moment they start a Python project with source code that needs more compute than a laptop can offer. What it does not give you is the full debugging experience of an IDE like PyCharm or VS Code. There is no clickable call stack, no variable explorer wired to a breakpoint, and no “step over” button in the toolbar. When a cell fails, you get a traceback and a blinking cursor.

That is not a limitation — it is a skill. Once you know how to read a traceback, how to drop into Python’s built-in pdb debugger, and which Colab-specific magics exist to help you, you can find any bug from any notebook. This tutorial teaches exactly that, with runnable examples for the errors Colab users hit most often: TypeError, IndexError, KeyError, ModuleNotFoundError, FileNotFoundError, and the dreaded “your session crashed after using all available RAM.”

The same debugging discipline applies whatever you build — a data pipeline, a Python sentiment analysis project, or a Python social media bot. The cell you are debugging is always the one that just failed; the technique is always: read the message, localise the line, inspect the state.

02 / EnvironmentHow Google Colab Runs Your Code

Colab is a hosted Jupyter notebook running on a Linux virtual machine. When you connect to a runtime, Google boots a fresh VM, starts a Python kernel, and links your notebook to it. Every cell you run executes in that same kernel, in order. Variables, imports, and functions defined in earlier cells stay alive in later cells until you restart the runtime.

Three consequences matter for debugging:

  • State is shared across cells. A variable you defined three cells ago is still in memory. If a cell behaves strangely, the cause may be a value set much earlier. Restarting the runtime (see §14) is the reliable way to test whether state is the problem.
  • The working directory is /content. Run !pwd in a cell and you will see /content. Files you upload through the file browser land here, and Google Drive mounts under /content/drive/MyDrive. Most “file not found” errors come from forgetting this (see §11).
  • RAM is finite and shared. The free tier gives roughly 12 GB of system RAM. Everything — loaded datasets, model weights, intermediate arrays — shares that budget. Exhaust it and the session crashes (see §13).

03 / TracebacksUnderstanding Traceback Messages

A traceback is the ordered list of function calls that led to the error. The single most important habit is to read it from the bottom up. The last line names the exception type and the message; the lines above it show where it happened. Here is a real one:

traceback (cell output)
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
<ipython-input-3-abc123>(2) <module>
      1 age = 25
----> 2 msg = "User age is " + age
      3 print(msg)

TypeError: can only concatenate str (not "int") to str

Reading it bottom-up:

  1. Last line — the exception: TypeError: can only concatenate str (not "int") to str. This tells you what went wrong: you tried to add a string and an integer.
  2. The arrow (---->) — the exact line: msg = "User age is " + age. This tells you where.
  3. The header — the cell and line number: <ipython-input-3-abc123>(2) means input cell 3, line 2 of that cell.

Ninety percent of debugging is steps 1 and 2: identify the exception type, then go to the marked line. The Python tutorial on errors and exceptions lists every built-in exception; bookmark it.

Colab shows a “simple” traceback by default

Colab trims tracebacks to keep the output readable. To see the full chain — every frame with its locals — switch the exception display mode with %xmode Verbose (covered in §15). You can also capture the full traceback as a string with the traceback module:

capture full traceback
import traceback

try:
    value = int("not a number")
except ValueError:
    traceback.print_exc()          # full traceback to the cell output
    print("Recovered: kept running.")

04 / print()The print() Statement Is Your First Debugger

Before reaching for a real debugger, add focused print() checkpoints. The goal is not to print everything — it is to confirm assumptions at the exact point where they break. Print the value and its type, because most bugs are type bugs in disguise. Run this broken cell:

buggy cell
# Buggy: silent wrong total because items contains a string
items = [10, 20, "thirty", 40]
total = 0
for x in items:
    total += x          # TypeError only when x is "thirty"
print("total =", total)  # never reached

The error is a TypeError, but you do not yet know which item is the culprit. Add a labelled checkpoint that prints index, type, and value at every step:

debugged with print()
items = [10, 20, "thirty", 40]
total = 0
for i, x in enumerate(items):
    print(f"[debug] i={i} type={type(x).__name__} value={x!r}")  # checkpoint
    if isinstance(x, (int, float)):
        total += x
    else:
        print(f"[warn] skipping non-numeric item at index {i}")
print("total =", total)

Now the output names the offender ([debug] i=2 type=str value='thirty') and the program no longer crashes. Notice the [warn] branch — a debug print that also guards the logic is often all you need.

Remove or gate debug prints before sharing

Littering a notebook with print calls makes it hard to read. Once a bug is fixed, delete the checkpoint lines, or wrap them in a flag: if DEBUG: print(...). For larger projects, prefer the logging module, which lets you set levels (DEBUG, INFO, WARNING) and turn them off in one place.

05 / pdbUsing Breakpoints and Python’s pdb Debugger

When a print is not enough — you need to stop execution mid-cell and inspect live variables — use Python’s built-in pdb debugger. In Colab it runs interactively in the cell’s output area. The classic entry point is pdb.set_trace():

pdb.set_trace()
import pdb

def average(scores):
    pdb.set_trace()              # execution pauses here
    return sum(scores) / len(scores)

average([70, 85, 90])

When the cell runs, execution pauses at the trace line and you get a (Pdb) prompt. From there you type commands to inspect state and step through code. Since Python 3.7 the cleaner, recommended way is the built-in breakpoint() function, which respects the PYTHONBREAKPOINT environment variable and defaults to pdb:

breakpoint()
def process(data):
    breakpoint()                 # modern, cleaner than pdb.set_trace()
    total = sum(data)
    return total / len(data)

process([10, 20, 0])

A typical session for the average function above looks like this — you can see exactly how each command reveals state:

pdb session (cell output)
> <ipython-input-1-...>(5)average()
-> return sum(scores) / len(scores)
(Pdb) p scores
[70, 85, 90]
(Pdb) p len(scores)
3
(Pdb) p sum(scores)
245
(Pdb) n
--Return--
> <ipython-input-1-...>(5)average()->81.666...
-> return sum(scores) / len(scores)
(Pdb) c

06 / pdb commandsEssential pdb Commands

You only need a handful of commands to debug almost anything. The table below is the working set; the full list is in the official pdb command reference.

CommandShortWhat it does
helphList commands, or h next for help on one command.
listlShow source around the current line. ll shows the whole function.
nextnRun the current line; step over function calls.
stepsRun the current line; step into function calls.
returnrRun until the current function returns.
continuecResume normal execution until the next breakpoint.
printpEvaluate and print an expression, e.g. p scores.
argsaPrint the current function’s arguments.
wherewPrint the call stack.
breakbSet a breakpoint: b 12 (line 12) or b myfunc.
display—Watch an expression; reprint it after every step.
quitqExit the debugger and stop execution.
Typing a bare expression prints it

Inside (Pdb), typing a variable name with no command evaluates and prints it — scores alone does the same as p scores. This is the fastest way to inspect state. Just remember n, s, c, p and q cover ~90% of real debugging.

07 / VariablesDebugging Variables and State

The most common variable bugs are typos in names (NameError) and wrong types (TypeError). The fix is always the same: print the variable and its type right before the line that uses it. Here is a name bug that is easy to miss:

NameError from a typo
def report(score):
    total = score + 5
    avreage = total / 2      # typo -> NameError later if used
    return avreage

print(report(80))           # 'avreage' is consistent, so it runs, but...
# A typo that does NOT match elsewhere raises NameError:
def total_score(points):
    return sum(point)       # NameError: name 'point' is not defined

The first function report actually runs (the typo avreage is used consistently), but it is wrong. The second function total_score raises a real NameError because point does not exist. The corrected version:

fixed
def total_score(points):
    return sum(points)      # corrected variable name

print(total_score([10, 20, 30]))   # 60

For more complex state — many variables, a long function — use the labelled trace pattern below. It prints the running result at each step so you can watch the variable evolve and catch the moment it goes wrong:

trace a variable through a loop
def classify(scores):
    categories = []
    for s in scores:
        if s >= 90:
            categories.append("high")
        elif s >= 50:
            categories.append("mid")
        else:
            categories.append("low")
        print(f"[trace] s={s} -> {categories[-1]!r} (len={len(categories)})")
    return categories

classify([95, 62, 30, 88])

08 / FunctionsDebugging Functions and Return Values

Two function bugs dominate notebooks: a function that returns None because the author forgot return, and a function that works but is called with the wrong arguments. The forgotten-return bug is vicious because the crash happens at the call site, not inside the function, so the traceback points at the wrong line:

forgotten return
def add(a, b):
    result = a + b        # computed but never returned -> returns None

total = add(3, 4)
print(total + 10)         # TypeError: NoneType + int

The traceback will point at print(total + 10) with TypeError: unsupported operand type(s) for +: 'int' and 'NoneType', but the real defect is in add. The fix:

fixed with return
def add(a, b):
    result = a + b
    return result         # explicit return

total = add(3, 4)
print(total + 10)         # 17
Use pdb to inspect a function mid-call

If you cannot tell what a function returns, drop a breakpoint() on its last line and call p result before the return. Or set a post-mortem with %debug (see §15) immediately after the exception — you land inside the failing frame with all locals live.

09 / LoopsDebugging Loops and Iteration Errors

Loop bugs fall into two families: boundary errors (IndexError from range that is too wide) and mutation-during-iteration bugs (silently skipping items). The boundary case:

IndexError in a loop
nums = [10, 20, 30]
for i in range(4):        # range(4) -> 0,1,2,3 but list has only 3 items
    print(nums[i])        # IndexError: list index out of range when i == 3

Two safe fixes — tie the range to the list length, or iterate directly:

fixed
nums = [10, 20, 30]
for i in range(len(nums)):   # always stays in bounds
    print(nums[i])

# Or iterate directly (preferred when you don't need the index):
for n in nums:
    print(n)

The mutation bug is more dangerous because it produces no exception — just a wrong result. Removing items from a list while looping over it shifts indices and skips elements:

mutating while iterating
items = [1, 2, 3, 4, 6]
for x in items:
    if x % 2 == 0:
        items.remove(x)   # mutates the list while iterating -> skips items
print(items)              # [1, 3, 4]  (4 was skipped!)

The output is [1, 3, 4], not the expected [1, 3] — the 4 was skipped. The rule: never mutate the structure you are iterating over. Build a new one instead:

fixed with a comprehension
items = [1, 2, 3, 4, 6]

# Build a new list instead of mutating the one you are iterating over:
items = [x for x in items if x % 2 != 0]
print(items)              # [1, 3]

10 / ImportsDebugging Import Errors

Colab comes with many packages pre-installed, but not all. Two errors cover almost every import problem: ModuleNotFoundError (the package name is wrong, or the package is not installed) and ImportError (the package exists but the name you are importing from it does not). A typo is the most common cause:

ModuleNotFoundError
import nump as np          # ModuleNotFoundError: No module named 'nump'
arr = np.array([1, 2, 3])

Check the spelling first — nump should be numpy. If the package is genuinely missing, install it from inside a cell with a leading ! (shell escape):

fixed import + install hint
import numpy as np         # correct name
arr = np.array([1, 2, 3])
print(arr)

# If the package is genuinely missing, install it first:
#   !pip install numpy
!pip install numpy

After installing, you usually do not need to restart the runtime for a pure-Python package; just run the import cell again. For packages that extend C extensions (or anything that loads at kernel start), use Runtime → Restart session and re-run your cells.

11 / PathsFixing File Path Errors in Colab

FileNotFoundError is the single most common Colab error for beginners, and the cause is almost always the same: the file is not in the directory you think it is. Remember that the working directory is /content. This cell fails on a fresh runtime:

FileNotFoundError
import pandas as pd
df = pd.read_csv("data.csv")        # FileNotFoundError in Colab
                                    # the file is NOT in the default path

The fix is to use the absolute path. Find where files live, then reference them explicitly:

fixed with absolute path
import pandas as pd, os

# 1) See where you actually are:
print(os.getcwd())                  # /content

# 2) Use the absolute path Colab uses for uploads:
df = pd.read_csv("/content/data.csv")

# 3) Or mount Drive once and read from there:
# from google.colab import drive
# drive.mount("/content/drive")
# df = pd.read_csv("/content/drive/MyDrive/data.csv")
Where Colab files actually live
  • Files uploaded via the file browser → /content/<filename> (they vanish when the runtime disconnects).
  • Google Drive, mounted → /content/drive/MyDrive/<filename> (persistent, survives disconnects).
  • Cloned Git repos → /content/<repo-name>/ after !git clone ….

Run !ls /content or os.getcwd() any time you are unsure. The official Colab I/O guide covers mounts and uploads in detail.

12 / Runtime errorsFixing Runtime Errors

These are the exceptions that fire while your code runs — the bread and butter of Python debugging. For each, the pattern is: read the message, find the line, fix the value or the operation.

TypeError — mixing incompatible types

TypeError
age = 25
msg = "User age is " + age     # TypeError: can only concatenate str (not "int") to str
print(msg)
fixed
age = 25
msg = "User age is " + str(age)        # option 1: convert explicitly
msg = f"User age is {age}"             # option 2: f-string (recommended)
print(msg)

KeyError — missing dictionary key

KeyError
user = {"name": "Ada", "role": "engineer"}
print(user["email"])     # KeyError: 'email
fixed with .get()
user = {"name": "Ada", "role": "engineer"}
print(user.get("email"))               # None
print(user.get("email", "not set"))    # "not set"

if "email" in user:
    print(user["email"])               # safe: key is known to exist

ZeroDivisionError — dividing by zero

ZeroDivisionError
def safe_div(a, b):
    return a / b        # ZeroDivisionError when b == 0

print(safe_div(10, 0))
fixed with a guard
def safe_div(a, b):
    if b == 0:
        raise ValueError("b cannot be zero")   # fail with a clear message
    return a / b

try:
    print(safe_div(10, 0))
except ValueError as e:
    print("Handled:", e)

AttributeError — wrong method name

AttributeError
nums = [3, 1, 2]
nums.revers()          # AttributeError: 'list' object has no attribute 'revers'
print(nums)
fixed
nums = [3, 1, 2]
nums.reverse()         # correct method name
print(nums)            # [2, 1, 3]

# Tip: in a cell, type nums. and press Tab to see valid attributes.

13 / MemoryFixing Memory Errors and RAM Crashes

Colab’s free runtime gives roughly 12 GB of system RAM. When you exceed it, the session does not raise a Python exception — it crashes with the message Your session crashed after using all available RAM, and the kernel restarts, wiping every variable. The fix is to keep memory under control deliberately.

The first habit: delete large objects you no longer need and force garbage collection with the gc module:

free memory on demand
import gc

# A big object you no longer need:
big = [0] * 50_000_000      # ~400 MB

# Free it instead of waiting for the session to end:
del big
gc.collect()                # force garbage collection now

The second habit: process large datasets in batches instead of loading them whole. This keeps peak memory low even when the total data is huge:

batch processing pattern
import gc

def process_batch(chunks):
    results = []
    for chunk in chunks:
        out = heavy_transform(chunk)
        results.append(out)
        del chunk, out      # release per-iteration memory
        gc.collect()
    return results
RAM crash vs Python exception

A RAM crash is not a MemoryError you can catch with try/except. The kernel is killed by the host. You must prevent it by design: smaller batches, generators instead of lists, del + gc.collect(), downcasting dtypes (float64 → float32), and streaming files instead of .read()-ing them whole. See the Colab FAQ for current resource limits.

14 / RestartRestarting the Runtime and Kernel

Because state persists across cells, a bug caused by stale variables can be invisible — the notebook “works” only because of leftover state from earlier experiments. When something behaves inexplicably, restart and run from the top.

Runtime → Restart session

Wipes all variables, imports, and loaded modules. The notebook cells stay; only the kernel state is cleared. Use this first when debugging state problems.

Runtime → Restart and run all

Restarts, then executes every cell top to bottom. This is the single best test of whether a notebook is reproducible. If it fails on re-run, the bug is a hidden ordering or state dependency.

Runtime → Disconnect and delete runtime

Destroys the VM entirely and starts fresh on a new one. Use this when a package install or a crashed GPU left the environment in a bad state.

“Restart and run all” catches most hidden bugs

Before sharing a notebook — for a class submission, a delivery project, or a pull request — always run Restart and run all. If it does not complete cleanly from an empty kernel, a reader who clones it will hit the same failure.

15 / MagicsColab Magic Commands for Debugging

Colab is built on IPython, which provides magic commands — lines starting with % that the kernel interprets specially. Three are invaluable for debugging.

%xmode — control traceback detail

IPython magics
%xmode Verbose        # richer tracebacks (callers + locals)
%xmode Plain           # minimal one-line tracebacks
%xmode Context         # default: shows source lines around the error

Switch to Verbose when a traceback is too short to localise the bug; it prints each frame’s local variables. Switch to Plain when the output is too noisy.

%pdb and %debug — automatic and post-mortem pdb

debug magics
%pdb on                # auto-drop into pdb whenever any cell raises
%pdb off               # turn it back off

# After an exception has already happened, drop into a post-mortem:
%debug

%pdb on makes Colab drop into pdb automatically whenever any cell raises an exception — no set_trace needed. If an exception already happened and you want to inspect it, run %debug in the next cell to enter a post-mortem session inside the failing frame, with all locals still alive. This is often the fastest way to find a bug: trigger it, then inspect the exact state that broke.

16 / ReferenceCommon Colab Errors and How to Fix Them

Error / messageCauseFix
NameError: name 'x' is not definedTypo in a variable name, or the cell that defined x was not run.Run cells in order from the top; check spelling. Runtime → Restart and run all to confirm.
ModuleNotFoundErrorPackage name misspelled, or package not installed in the runtime.Fix the spelling; if missing, !pip install <name> then re-run the import.
FileNotFoundErrorPath is relative and the file is not in /content.Use the absolute path (/content/… or /content/drive/MyDrive/…). Run !pwd to confirm.
TypeErrorOperating on incompatible types (e.g. str + int).Convert explicitly (str(age)) or use an f-string. Print type(x) at the failing line.
IndexErrorLoop range wider than the sequence, or off-by-one indexing.Use range(len(seq)) or iterate directly; use .get() for dicts.
KeyErrorAccessing a dict key that does not exist.Use d.get(key, default) or test key in d first.
AttributeErrorMethod or attribute name is wrong for the object’s type.Check spelling; type obj. and press Tab for valid attributes.
ZeroDivisionErrorDividing by a variable that is zero.Guard with if b == 0 or use a try/except.
Your session crashed after using all available RAMPeak memory exceeded the ~12 GB free-tier limit.Process in batches; del large objects + gc.collect(); downcast dtypes; stream files.
ValueErrorRight type, wrong value (e.g. int("abc")).Validate input before the call, or wrap in try/except ValueError.
ImportError: cannot import nameThe name does not exist in the installed package version.Check the package docs for your version; reinstall or upgrade with !pip install --upgrade.
Transport endpoint is not connectedGoogle Drive mount dropped after a disconnect.Re-mount: drive.mount("/content/drive") (forces re-auth if needed).

17 / WalkthroughA Complete Debugging Walkthrough

Putting it all together. Suppose you have a function that should average scores and print a report, but it crashes. Here is the broken cell:

the broken cell
# Buggy: silent wrong total because items contains a string
items = [10, 20, "thirty", 40]
total = 0
for x in items:
    total += x          # TypeError only when x is "thirty"
print("total =", total)  # never reached

Follow the method step by step:

Read the traceback bottom-up

Last line: TypeError: unsupported operand type(s) for +=: 'int' and 'str'. Arrow points at total += x. So x is a string at some point.

Confirm with a print checkpoint

Add print(f"[debug] i={i} type={type(x).__name__} value={x!r}") inside the loop. Output reveals i=2 type=str value='thirty' — the third item is a string.

Decide the fix

The list mixes types. Either coerce with int(x), or skip non-numeric items. Here skipping is correct because "thirty" is bad source data.

Apply the fix and re-run

Wrap the addition in if isinstance(x, (int, float)). The cell now runs and prints total = 70.

Verify with Restart and run all

If the fix survives a fresh kernel, the bug is truly gone, not papered over by stale state.

The corrected cell is the print_fix example from §4. Notice that no real debugger was needed — a single labelled print was enough. That is the normal case. Reach for pdb when a print cannot pause long enough for you to inspect a complex object.

18 / ChecklistA Debugging Checklist You Can Reuse

  • Read the traceback bottom-up: exception type first, then the marked line.
  • Reproduce the error from a clean state with Runtime → Restart and run all.
  • Add a print of value and type() at the line before the failure.
  • For complex state, drop in breakpoint() and use n, s, p, c.
  • Switch %xmode Verbose if the traceback is too short; %debug for a post-mortem.
  • Check file paths with !pwd and !ls /content before assuming a file is missing.
  • For RAM crashes, switch to batches, del + gc.collect(), and downcast dtypes.
  • After the fix, delete debug prints or gate them behind a DEBUG flag.

19 / OutcomesWhat You Will Learn from This Guide

  • How Google Colab executes your cells and why shared state causes hidden bugs.
  • How to read any Python traceback in seconds by working bottom-up.
  • How to use print() checkpoints and Python’s pdb debugger inside notebooks.
  • How to fix the eight exception types Colab users hit most.
  • How to prevent RAM crashes with batching and garbage collection.
  • How to use IPython magics (%xmode, %pdb, %debug) to debug faster.

20 / Wrap-upConclusion

Debugging in Google Colab is not harder than debugging anywhere else — it just uses different tools. A traceback read bottom-up, a well-placed print that shows type as well as value, and the four pdb commands n, s, p, c will locate almost any bug. Add the Colab-specific habits — /content paths, batched memory, Restart and run all — and the environment stops surprising you.

The fastest way to make these habits automatic is to apply them on real code. Pick a project, break it on purpose, and walk through the checklist above. For more projects to practise on, browse the Python projects with source code collection on Darekdari and debug one end to end.

21 / FAQFrequently Asked Questions

Does pdb work inside Google Colab? +

Yes. Colab is built on IPython, so pdb runs interactively in a cell’s output area. Insert breakpoint() (or pdb.set_trace()) where you want to pause, run the cell, and type commands at the (Pdb) prompt. You can also enable automatic post-mortem debugging with %pdb on, or enter a debugger after an exception with %debug.

Why does my file path work locally but fail in Colab? +

Your machine and the Colab VM are different computers with different filesystems. Colab’s working directory is /content, not your project folder. Use absolute paths such as /content/data.csv for uploads or /content/drive/MyDrive/data.csv for files on Drive. Run !pwd to confirm where you are. See the Colab I/O guide for mounts and uploads.

What does “your session crashed after using all available RAM” mean? +

It means peak memory exceeded the free tier’s ~12 GB and the host killed the kernel. It is not a Python MemoryError you can catch. Prevent it by processing data in batches, deleting large objects with del plus gc.collect(), downcasting array dtypes, and streaming files instead of reading them whole. The Colab FAQ lists current limits.

Should I restart the runtime while debugging? +

Yes, whenever behaviour is inconsistent. Because state persists across cells, a stale variable can make a notebook appear to work when it is actually broken. Runtime → Restart and run all is the most reliable test of whether your notebook is reproducible from a clean kernel.

Is print() debugging bad practice? +

No — it is the fastest tool for most bugs, and it is always available. The mistake is leaving debug prints scattered in shared notebooks. Delete them once the bug is fixed, or gate them behind a DEBUG flag. For larger or long-running projects, the logging module gives you levels and a single off switch.

How do I see the full traceback in Colab? +

Run %xmode Verbose to show every frame with its local variables, or capture the traceback as a string with traceback.format_exc() from the traceback module. Switch back with %xmode Context (the default).

Scroll to Top