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.
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!pwdin 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:
---------------------------------------------------------------------------
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 strReading it bottom-up:
- 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. - The arrow (
---->) — the exact line:msg = "User age is " + age. This tells you where. - 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 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:
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: 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 reachedThe 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:
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.
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():
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:
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:
> <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) c06 / 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.
| Command | Short | What it does |
|---|---|---|
help | h | List commands, or h next for help on one command. |
list | l | Show source around the current line. ll shows the whole function. |
next | n | Run the current line; step over function calls. |
step | s | Run the current line; step into function calls. |
return | r | Run until the current function returns. |
continue | c | Resume normal execution until the next breakpoint. |
print | p | Evaluate and print an expression, e.g. p scores. |
args | a | Print the current function’s arguments. |
where | w | Print the call stack. |
break | b | Set a breakpoint: b 12 (line 12) or b myfunc. |
display | — | Watch an expression; reprint it after every step. |
quit | q | Exit the debugger and stop execution. |
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:
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 definedThe 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:
def total_score(points):
return sum(points) # corrected variable name
print(total_score([10, 20, 30])) # 60For 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:
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:
def add(a, b):
result = a + b # computed but never returned -> returns None
total = add(3, 4)
print(total + 10) # TypeError: NoneType + intThe 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:
def add(a, b):
result = a + b
return result # explicit return
total = add(3, 4)
print(total + 10) # 17If 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:
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 == 3Two safe fixes — tie the range to the list length, or iterate directly:
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:
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:
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:
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):
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 numpyAfter 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:
import pandas as pd
df = pd.read_csv("data.csv") # FileNotFoundError in Colab
# the file is NOT in the default pathThe fix is to use the absolute path. Find where files live, then reference them explicitly:
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")- 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
age = 25
msg = "User age is " + age # TypeError: can only concatenate str (not "int") to str
print(msg)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
user = {"name": "Ada", "role": "engineer"}
print(user["email"]) # KeyError: 'emailuser = {"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 existZeroDivisionError — dividing by zero
def safe_div(a, b):
return a / b # ZeroDivisionError when b == 0
print(safe_div(10, 0))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
nums = [3, 1, 2]
nums.revers() # AttributeError: 'list' object has no attribute 'revers'
print(nums)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:
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 nowThe second habit: process large datasets in batches instead of loading them whole. This keeps peak memory low even when the total data is huge:
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 resultsA 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.
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
%xmode Verbose # richer tracebacks (callers + locals)
%xmode Plain # minimal one-line tracebacks
%xmode Context # default: shows source lines around the errorSwitch 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
%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 / message | Cause | Fix |
|---|---|---|
NameError: name 'x' is not defined | Typo 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. |
ModuleNotFoundError | Package name misspelled, or package not installed in the runtime. | Fix the spelling; if missing, !pip install <name> then re-run the import. |
FileNotFoundError | Path is relative and the file is not in /content. | Use the absolute path (/content/… or /content/drive/MyDrive/…). Run !pwd to confirm. |
TypeError | Operating on incompatible types (e.g. str + int). | Convert explicitly (str(age)) or use an f-string. Print type(x) at the failing line. |
IndexError | Loop range wider than the sequence, or off-by-one indexing. | Use range(len(seq)) or iterate directly; use .get() for dicts. |
KeyError | Accessing a dict key that does not exist. | Use d.get(key, default) or test key in d first. |
AttributeError | Method or attribute name is wrong for the object’s type. | Check spelling; type obj. and press Tab for valid attributes. |
ZeroDivisionError | Dividing by a variable that is zero. | Guard with if b == 0 or use a try/except. |
Your session crashed after using all available RAM | Peak memory exceeded the ~12 GB free-tier limit. | Process in batches; del large objects + gc.collect(); downcast dtypes; stream files. |
ValueError | Right type, wrong value (e.g. int("abc")). | Validate input before the call, or wrap in try/except ValueError. |
ImportError: cannot import name | The 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 connected | Google 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:
# 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 reachedFollow 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
printof value andtype()at the line before the failure. - For complex state, drop in
breakpoint()and usen,s,p,c. - Switch
%xmode Verboseif the traceback is too short;%debugfor a post-mortem. - Check file paths with
!pwdand!ls /contentbefore 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
DEBUGflag.
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’spdbdebugger 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).
