Cuando un programa en Python se ejecuta pero produce un resultado incorrecto, añadir más llamadas a print() puede convertirse rápidamente en una solución difícil de mantener. Un depurador permite pausar el programa, inspeccionar valores, ejecutar una línea cada vez y comprender exactamente cómo el código llegó a un determinado estado.
En esta guía aprenderás a depurar Python en VS Code con breakpoints, controles paso a paso, variables, panel Watch, pila de llamadas, puntos condicionales, logpoints y configuraciones de launch.json. También revisaremos problemas frecuentes relacionados con el intérprete y los entornos virtuales.
Qué necesitas
Instala Visual Studio Code, Python y la extensión oficial de Python de Microsoft. La extensión Python Debugger proporciona el adaptador utilizado en las sesiones actuales.
La documentación oficial de depuración de Python en VS Code explica las configuraciones y controles disponibles.
Abrir una carpeta de proyecto
Abre la carpeta completa que contiene tus archivos, no solamente un archivo suelto. Una carpeta de trabajo permite guardar configuraciones, detectar entornos virtuales y crear .vscode/launch.json.
Crea carrito.py:
def calcular_total(precios, descuento=0):
subtotal = sum(precios)
valor_descuento = subtotal * descuento
return subtotal - valor_descuento
articulos = [19.90, 5.50, 12.00]
total = calcular_total(articulos, descuento=10)
print(f"Total: {total:.2f}")El código tiene un error lógico: la función espera un descuento decimal como 0.10, pero recibe 10. La sintaxis es válida, así que Python ejecuta el archivo y muestra un total negativo.
Seleccionar el intérprete correcto
Haz clic en el indicador de Python de la barra inferior o ejecuta Python: Select Interpreter desde la paleta de comandos. Elige el entorno donde estén instaladas las dependencias del proyecto.
Un intérprete incorrecto puede causar paquetes ausentes, una versión inesperada de Python o variables de entorno diferentes.
Crear el primer breakpoint
Haz clic en el margen izquierdo junto a esta línea:
valor_descuento = subtotal * descuentoAparecerá un punto rojo. El depurador pausará antes de ejecutar esa línea. También puedes alternar un breakpoint con F9.
Iniciar la depuración
Abre el archivo, entra en Run and Debug y pulsa F5. En un script sencillo, selecciona la configuración para el archivo Python actual.
Cuando el programa se detiene, VS Code muestra Variables, Watch, Call Stack y Breakpoints. La línea activa aparece resaltada.
Inspeccionar variables
En el ejemplo, revisa:
precios: la lista de valores.descuento: contiene10.subtotal: suma de los precios.
El valor de descuento revela la causa. Corrige la llamada:
total = calcular_total(articulos, descuento=0.10)Controles principales
- Continue (F5): continúa hasta el siguiente breakpoint.
- Step Over (F10): ejecuta la línea sin entrar en funciones llamadas.
- Step Into (F11): entra en la función de la línea actual.
- Step Out (Shift + F11): termina la función actual.
- Restart: reinicia la sesión.
- Stop (Shift + F5): finaliza la depuración.
Step Over y Step Into
def aplicar_impuesto(importe, tasa):
return importe * (1 + tasa)
def crear_factura(precios):
subtotal = sum(precios)
total = aplicar_impuesto(subtotal, 0.08)
return total
print(crear_factura([10, 20, 30]))Si estás en la llamada a aplicar_impuesto(), Step Over calcula el resultado y permanece en crear_factura(). Step Into abre la función para inspeccionar importe y tasa.
Panel Watch
Watch recalcula expresiones cada vez que la ejecución se pausa:
subtotal * descuento
len(precios)
subtotal - valor_descuento
all(precio >= 0 for precio in precios)Evita expresiones con efectos secundarios porque podrían modificar el estado del programa.
Debug Console
Con el programa pausado, puedes evaluar expresiones:
subtotal
precios[0]
type(descuento)
subtotal * 0.10La consola es útil para experimentar, pero los cambios desaparecen al reiniciar. La solución definitiva debe guardarse en el código.
Comprender la pila de llamadas
Call Stack muestra el camino seguido hasta la línea actual:
main
crear_informe
calcular_promedio
validar_valoresAl seleccionar un marco, VS Code muestra las variables locales de esa función. Es especialmente útil cuando el error aparece lejos del punto donde se originaron los datos.
Breakpoints condicionales
En un bucle grande, no conviene detenerse en cada iteración.
pedidos = [15, 42, -8, 27, 100]
for indice, importe in enumerate(pedidos):
procesado = importe * 1.1
print(indice, procesado)Haz clic derecho sobre el breakpoint y añade una condición como:
importe < 0
indice == 3
procesado > 50Hit counts y logpoints
Un hit count pausa después de que una línea se ejecute cierto número de veces. Un logpoint escribe un mensaje en la consola sin detener el programa.
Ejemplo de logpoint:
Procesando pedido {indice}: importe={importe}Para registros permanentes, utiliza el módulo logging. Los logpoints son una ayuda temporal del editor.
Depurar excepciones
En la sección Breakpoints puedes activar la pausa cuando se genera una excepción.
def promedio(valores):
return sum(valores) / len(valores)
print(promedio([]))Al detenerse en ZeroDivisionError, verás que la lista está vacía y podrás seguir la pila para localizar su origen.
Crear launch.json
Los archivos sencillos no necesitan configuración. Utiliza launch.json cuando debas pasar argumentos, variables de entorno, un directorio de trabajo o un módulo concreto.
{
"version": "0.2.0",
"configurations": [
{
"name": "Depurar archivo Python actual",
"type": "debugpy",
"request": "launch",
"program": "${file}",
"console": "integratedTerminal",
"justMyCode": true
}
]
}Pasar argumentos
{
"name": "Depurar informe",
"type": "debugpy",
"request": "launch",
"program": "${workspaceFolder}/informe.py",
"args": ["ventas.csv", "--formato", "json"],
"console": "integratedTerminal"
}No guardes contraseñas ni tokens dentro de esta configuración.
Depurar pruebas
La vista Testing permite descubrir pruebas de unittest y pytest. Coloca un breakpoint en la aplicación o en la prueba y utiliza la opción de depuración.
La guía de Pytest en Python explica cómo crear pruebas, comprobar excepciones y organizar archivos.
Problemas frecuentes
El breakpoint aparece gris
Guarda el archivo, confirma que es el archivo ejecutado y revisa el intérprete y la configuración seleccionada.
No se puede importar un paquete
Selecciona el entorno donde se instaló la biblioteca y compara su ruta con la terminal.
input() no funciona
Utiliza integratedTerminal para programas interactivos.
El depurador entra en bibliotecas
Mantén justMyCode activado para trabajar principalmente con tu propio código.
El programa se comporta distinto
Compara el directorio de trabajo, los argumentos, las variables de entorno y el intérprete con la ejecución habitual.
Rutina práctica de depuración
- Reproduce el problema con una entrada pequeña.
- Lee el error completo o describe el resultado incorrecto.
- Coloca un breakpoint antes del primer estado sospechoso.
- Inspecciona entradas y suposiciones.
- Avanza una decisión cada vez.
- Utiliza la pila de llamadas para localizar el origen.
- Corrige la causa, no solamente el síntoma.
- Añade una prueba que evite la regresión.
Conclusión
Para depurar Python en VS Code de forma eficaz, comienza con el intérprete correcto, pausa antes del posible fallo, revisa variables y sigue las decisiones con los controles paso a paso. Los breakpoints condicionales y logpoints ayudan en bucles grandes, mientras que launch.json hace reproducibles las ejecuciones complejas.
La mejor práctica combina depuración, mensajes de error claros, logging y pruebas automatizadas.
Lecturas relacionadas
- Evita problemas de intérprete y dependencias con la guía de entornos virtuales en Python.
- Convierte los mensajes temporales de depuración en registros útiles con el módulo logging de Python.
