Depurar Python con pdb: guía práctica para principiantes

pdb es el depurador interactivo incluido en Python. Permite detener un programa, inspeccionar variables, avanzar línea por línea, entrar en funciones y comprobar el flujo real sin llenar el código de llamadas a print(). Es especialmente útil cuando un error depende del estado acumulado, aparece dentro de un bucle o no produce una excepción clara.

También puedes combinarlo con la depuración de Python en VS Code, las técnicas de debug con f-strings, el manejo de try y except y el módulo logging. Cada herramienta resuelve un tipo distinto de problema.

Crear un punto de interrupción

Desde Python 3.7 puedes usar la función integrada breakpoint():

def calcular_total(precios):
    subtotal = sum(precios)
    breakpoint()
    impuesto = subtotal * 0.21
    return subtotal + impuesto

print(calcular_total([10, 20, 30]))

Cuando la ejecución alcanza esa línea, aparece el prompt (Pdb). El programa queda pausado y acepta comandos.

Primeros comandos de pdb

Los comandos fundamentales son:

p variable     # muestra el valor
pp variable    # muestra estructuras con formato
n              # ejecuta la siguiente línea del contexto actual
s              # entra en una función llamada
c              # continúa hasta el siguiente breakpoint
l              # muestra líneas de código cercanas
q              # abandona la depuración
h              # abre la ayuda

En el ejemplo anterior puedes escribir:

(Pdb) p subtotal
60
(Pdb) n
(Pdb) p impuesto
12.6

Diferencia entre next y step

n ejecuta la siguiente línea sin entrar en las funciones llamadas. s entra en la función y permite seguir su ejecución interna:

def aplicar_descuento(total, porcentaje):
    return total * (1 - porcentaje)


def procesar(total):
    breakpoint()
    return aplicar_descuento(total, 0.10)

Con n, la llamada se trata como una sola operación. Con s, el depurador entra en aplicar_descuento. Usa step cuando sospechas que el problema está dentro de la función.

Mostrar el contexto del código

El comando l muestra unas líneas alrededor de la posición actual. ll intenta mostrar la función completa. Esto ayuda cuando estás depurando desde el terminal y no tienes un editor abierto.

Inspeccionar tipos y expresiones

Puedes evaluar expresiones válidas de Python:

(Pdb) p type(datos)
(Pdb) p len(datos)
(Pdb) p datos[:3]
(Pdb) p usuario.get("email")

Evita ejecutar expresiones con efectos secundarios, como eliminar archivos o modificar una base de datos. Durante una sesión de depuración, una expresión puede ejecutarse realmente.

Modificar variables temporalmente

Es posible cambiar valores para comprobar una hipótesis:

(Pdb) p descuento
0.5
(Pdb) descuento = 0.05
(Pdb) c

Este cambio solo afecta a la ejecución actual. Sirve para verificar si un valor concreto causa el fallo, pero después debes corregir el código fuente.

Depurar un bucle sin detenerse siempre

Colocar breakpoint() dentro de un bucle puede ser molesto. Usa una condición:

for indice, valor in enumerate(valores):
    if valor < 0:
        breakpoint()
    procesar(valor)

El programa se detiene únicamente cuando aparece un dato sospechoso.

Breakpoints desde pdb

Puedes iniciar un script directamente:

python -m pdb programa.py

Después establece un breakpoint por número de línea o función:

(Pdb) b 25
(Pdb) b programa.procesar
(Pdb) c

break sin argumentos lista los puntos existentes. clear elimina uno o varios.

Breakpoints condicionales

Para detenerte solo bajo una condición:

(Pdb) b 25, usuario_id == 42

Este recurso es útil en bucles largos o procesamiento por lotes. Asegúrate de que las variables usadas en la condición existen cuando se evalúa esa línea.

Navegar por la pila de llamadas

Cuando varias funciones se llaman entre sí, utiliza:

where  # muestra la pila
up     # sube al marco llamador
down   # baja al marco siguiente

Cada marco tiene sus propias variables locales. Un valor correcto en una función puede haber sido creado incorrectamente en la función que la llamó. Navegar por la pila ayuda a encontrar el origen y no solo el lugar donde el error se manifestó.

Continuar hasta salir de una función

r o return continúa hasta que la función actual termina. Resulta útil cuando ya revisaste la parte interna y quieres observar el valor devuelto.

Depurar una excepción después de ocurrir

El módulo permite depuración post mortem:

import pdb

try:
    resultado = 10 / 0
except Exception:
    pdb.post_mortem()

El depurador se abre en el punto donde ocurrió la excepción. En entornos de desarrollo también puedes ejecutar un script con python -m pdb y revisar el traceback.

Usar pdb desde una función específica

La forma clásica sigue disponible:

import pdb

pdb.set_trace()

breakpoint() es más flexible porque respeta la variable de entorno PYTHONBREAKPOINT. Puedes desactivarlo sin editar el código:

PYTHONBREAKPOINT=0 python programa.py

En Windows PowerShell, establece la variable con la sintaxis correspondiente del shell.

No dejes breakpoints en producción

Un breakpoint() activo puede detener un proceso web, una tarea programada o un contenedor esperando entrada que nunca llegará. Revisa el código antes de desplegar y utiliza linters o búsquedas automáticas en CI.

pdb frente a print y logging

print() es rápido para una comprobación pequeña, pero requiere anticipar qué variable observar. pdb permite explorar el estado de manera interactiva. logging registra información durante ejecuciones largas o en producción. Una estrategia práctica es reproducir el fallo localmente, usar pdb para encontrar la causa y añadir logs útiles para futuras incidencias.

Ejemplo completo

def promedio(numeros):
    if not numeros:
        raise ValueError("La lista está vacía")

    total = 0
    for numero in numeros:
        total += numero

    breakpoint()
    return total / len(numeros)


datos = [10, 20, "30"]
print(promedio(datos))

El error ocurre antes del breakpoint porque no se puede sumar una cadena a un entero. Mueve temporalmente el breakpoint dentro del bucle o ejecuta el programa con python -m pdb para inspeccionar cada elemento. El objetivo es identificar que "30" debería convertirse o rechazarse durante la validación.

La documentación oficial de pdb describe todos los comandos y formas de invocación. La documentación de breakpoint() explica cómo la función se conecta con el depurador y cómo se configura mediante PYTHONBREAKPOINT.

Errores frecuentes

Los problemas habituales son confundir next con step, modificar variables y olvidar aplicar la corrección al código, ejecutar expresiones con efectos secundarios, dejar breakpoints en producción y abandonar la sesión sin revisar la pila. También es frecuente detenerse demasiado tarde; coloca el punto antes de la operación que cambia el estado sospechoso.

Conclusión

pdb permite observar la ejecución real de un programa sin depender de suposiciones. Con breakpoint(), p, n, s, where y breakpoints condicionales puedes seguir datos, llamadas y decisiones paso a paso. Usado junto con pruebas y logging, el depurador reduce el tiempo necesario para encontrar la causa de errores complejos.