Depuración del código de Python en Visual Studio

Visual Studio proporciona una experiencia de depuración completa para Python. En este artículo, explorará cómo adjuntar el depurador a procesos en ejecución y evaluar expresiones en las ventanas Inspección e Inmediato. En el depurador, puede inspeccionar variables locales, establecer puntos de interrupción, entrar, salir y avanzar entre instrucciones, Set Next Statement, y más.

Para obtener información de depuración específica del escenario, consulte los siguientes artículos:

• Depuración remota de Linux
• Mixed-mode Python/C++ debugging (Depuración en modo mixto Python/C++)
• Symbols for mixed-mode debugging (Símbolos de depuración en modo mixto)

Prerrequisitos

• Visual Studio instalado con compatibilidad con cargas de trabajo de Python. Para obtener más información, consulte Instalación de compatibilidad con Python en Visual Studio.

• Código de Python que se va a usar con el depurador.

Depuración de código con o sin un proyecto

Si desea controlar el entorno y los argumentos de Python, cree primero un proyecto para el código. Puede crear un proyecto con la plantilla de proyecto A partir del código de Python existente. Para obtener más información, consulte Creación de un proyecto a partir de archivos de código de Python existentes.

Sin embargo, no necesita un archivo de proyecto o solución en Visual Studio para depurar el código de Python. Para depurar código en un archivo de Python independiente, abra el archivo en Visual Studio y seleccione Depurar>Iniciar depuración. Visual Studio inicia el script con el entorno predeterminado global y sin argumentos. Después, tiene soporte completo de depuración para su código. Para obtener más información, consulte entornos de Python.

Explora la depuración básica

El flujo de trabajo de depuración básico implica la configuración de puntos de interrupción, recorrer el código paso a paso, inspeccionar valores y manejar excepciones. Para iniciar una sesión de depuración, seleccione Depurar>Iniciar depuración o use el método abreviado de teclado F5. Para un proyecto, estas acciones lanzan el archivo de inicio con el entorno activo del proyecto y cualquier argumento de línea de comandos o rutas de búsqueda especificados para Propiedades del proyecto. Para configurar las propiedades, consulte Establecer opciones de depuración de proyectos.

Establecimiento del archivo de inicio del proyecto

El archivo de inicio de un proyecto se muestra en negrita en Explorador de soluciones. Puede elegir qué archivo se va a usar como archivo de inicio.

• Para especificar un archivo de proyecto como archivo de inicio, haga clic con el botón derecho en el archivo y seleccione Establecer como elemento de inicio.

En Visual Studio 2017, versión 15.6 y posteriores, verá una alerta si no tiene establecido un archivo de inicio especificado. Las versiones anteriores de Visual Studio podrían abrir una ventana Salida con el intérprete de Python en ejecución, o la ventana Salida se abre y se cierra brevemente.

Especificar el entorno activo

Si usa un archivo de proyecto, el depurador siempre comienza con el entorno de Python activo para el proyecto. Puede cambiar el entorno activo actual. Para obtener más información, consulte Seleccionar un entorno de Python para un proyecto.

Si va a depurar un archivo de código de Python independiente, Visual Studio inicia el script con el entorno predeterminado global y sin argumentos.

Establecer puntos de interrupción

Los puntos de interrupción detienen la ejecución del código en un punto marcado para poder inspeccionar el estado del programa.

Algunos puntos de interrupción de Python pueden resultar sorprendentes para aquellos desarrolladores que hayan trabajado con otros lenguajes de programación. En Python, todo el archivo es código ejecutable, por lo que Python ejecuta el archivo cuando se carga para procesar cualquier definición de función o clase de nivel superior. Si se establece un punto de interrupción, es posible que vea que el depurador se detiene a medio camino de una declaración de clase. Este comportamiento es correcto, aunque a veces es sorprendente.

• Para establecer un punto de interrupción, seleccione en el margen izquierdo del editor de código o haga clic con el botón derecho en una línea de código y seleccione Punto de interrupción>Insertar punto de interrupción. Aparece un punto rojo en cada línea que tiene un punto de interrupción establecido.

  

• Para quitar un punto de interrupción, seleccione el punto rojo o haga clic con el botón derecho en la línea de código y seleccione punto de interrupción>Eliminar punto de interrupción. También puede deshabilitar un punto de interrupción seleccionando el punto rojo y seleccionando Punto de interrupción>Deshabilitar punto de interrupción.

  

Establecimiento de condiciones y acciones

Puede personalizar las condiciones en las que se desencadena un punto de interrupción, como la interrupción solo cuando una variable se establece en un determinado valor o intervalo de valores.

• Para establecer condiciones, haga clic con el botón derecho en el punto rojo del punto de interrupción y seleccione Condiciones. Se abre el cuadro de diálogo Configuración de Puntos de Interrupción.

  En el cuadro de diálogo, puede agregar varias condiciones y crear expresiones condicionales mediante código de Python. Para obtener todos los detalles sobre esta característica de Visual Studio, vea Breakpoint conditions (Condiciones de los puntos de interrupción).

  

• También tiene las opciones para establecer Acciones para un punto de interrupción. Puede crear un mensaje para iniciar sesión en la ventana Salida y, opcionalmente, especificar para continuar la ejecución automáticamente.

  

  El registro de un mensaje crea un punto de seguimiento que no agrega código de registro a la aplicación directamente.

En función de cómo configure las condiciones y acciones de un punto de interrupción, el icono rojo del margen izquierdo cambia para indicar la configuración. Es posible que vea la forma de punto, un temporizador del reloj o un diamante.

Paso a paso por el código

Cuando Visual Studio detiene la ejecución de código en un punto de interrupción, hay varios comandos que puede usar para recorrer el código o ejecutar bloques de código antes de interrumpir de nuevo. Los comandos están disponibles en algunos lugares de Visual Studio, incluida la barra de herramientas del Depurador, el menú Depurar, el menú contextual con el botón derecho en el editor de código, y a través de atajos de teclado.

En la tabla siguiente se resumen estos comandos y se proporciona el método abreviado de teclado:

Comando	Acceso directo	Descripción
Stop	Mayús + F5	Detenga la sesión de depuración.
Reiniciar	Ctrl + Mayús + F5	Reinicie la sesión de depuración actual.
Continue	F5	Ejecute el código hasta llegar al siguiente punto de interrupción.
Depurar paso a paso por instrucciones	F11	Ejecute la siguiente instrucción y deténgala. Si la siguiente instrucción es una llamada a una función, el depurador se detiene en la primera línea de la función llamada.
Paso a paso por procedimientos	F10	Ejecute la siguiente instrucción, incluida la realización de una llamada a una función (ejecutando todo su código) y aplicando cualquier valor devuelto. Este comando permite omitir fácilmente las funciones que no es necesario depurar.
Paso a paso para salir	Mayús+F11	Ejecute el código hasta el final de la función actual y, a continuación, paso a la instrucción de llamada. Este comando es útil cuando no es necesario depurar el resto de la función actual.
Ejecutar hasta el cursor	Ctrl+F10	Ejecuta el código hasta la ubicación del cursor en el editor. Este comando permite omitir fácilmente un segmento de código que no es necesario depurar.
Establecer instrucción siguiente	Ctrl+Mayús+F10	Cambie el punto actual de ejecución en el código a la ubicación del cursor. Este comando le permite omitir por completo la ejecución de un segmento de código, por ejemplo, cuando sabe que el código es erróneo o que produce un efecto secundario no deseado.
Mostrar la instrucción siguiente	Alt+Núm+\	Regrese a la siguiente instrucción para ejecutarla en el código. Este comando le ayuda a localizar el lugar en el código donde se detiene el depurador.

Inspección y modificación de valores

Al detener la ejecución de código en el depurador, puede inspeccionar y modificar los valores de las variables. También puede usar la ventana Inspección para supervisar variables individuales y expresiones personalizadas. Para obtener más información, consulte Inspeccionar variables.

• Para ver un valor utilizando la función DataTips durante la depuración, pase el ratón sobre cualquier variable en el editor. Puede seleccionar el valor de la variable para cambiarlo:

  

• Para usar la ventana Automático, seleccione Depurar>Ventanas>Automático. Esta ventana contiene variables y expresiones que están cerca de la instrucción actual. Puede hacer doble clic en la columna de valor o seleccionar y escribir F2 para editar el valor:

  

  Para obtener más información sobre el uso de la ventana Automático, consulte Inspeccionar variables en las ventanas Automático y Locales.

• Para usar la ventana Locales, seleccione Depuración>Ventanas>Locales. En esta ventana se muestran todas las variables que están en el ámbito actual, que se pueden editar de nuevo:

  

  Para obtener más información sobre el uso de la ventana Locales, consulte Inspeccionar variables en las ventanas Automático y Locales.

• Para usar las ventanas Inspección, seleccione Depurar>Ventanas>Inspección>Inspección 1-4. Esta opción permite escribir expresiones arbitrarias de Python y ver los resultados. Las expresiones se vuelven a evaluar para cada paso:

  

  Para obtener más información sobre el uso de la ventana Inspección, consulte Inspeccionar variables con las ventanas Inspeccionar e Inspección rápida.

• Para inspeccionar un valor de cadena, seleccione Ver (lupa) a la derecha de la entrada Valor. Los tipos str, unicode, bytesy bytearray están disponibles para su inspección.

  En el menú desplegable Ver se muestran cuatro opciones de visualización: Texto, HTML, XML o JSON.

  

  Después de seleccionar una visualización, un cuadro de diálogo emergente muestra el valor de cadena sin comilla según el tipo seleccionado. Puede ver la cadena de texto con ajuste y desplazamiento, resaltado de sintaxis y vistas en árbol. Estas visualizaciones pueden ayudar a depurar problemas con cadenas largas y complejas.

Ver excepciones

Si se produce un error en el programa durante la depuración, pero no tiene un controlador de excepciones para él, el depurador se interrumpe en el punto de la excepción:

Cuando se produce un error, puede inspeccionar el estado actual del programa, incluida la pila de llamadas. Sin embargo, si recorre el código, el proceso de depuración continúa lanzando la excepción hasta que se controla o el programa se cierra.

• Para ver una vista ampliada de las excepciones, seleccione Depurar>Windows>Configuración de excepciones.

  

  En la ventana Configuración de excepciones, la casilla situada junto a una excepción controla si el depurador siempre se interrumpe cuando se produce dicha excepción.

• Para interrumpir con más frecuencia una excepción determinada, active la casilla situada junto a la excepción en la ventana Configuración de excepciones.

• De forma predeterminada, la mayoría de las excepciones se interrumpen cuando no se encuentra un controlador de excepciones en el código fuente. Para cambiar este comportamiento, haga clic con el botón derecho en cualquier excepción y modifique la opción Continuar cuando no se controle en el código de usuario. Para que la excepción se interrumpa con menos frecuencia, anule la selección de esta opción.

• Para configurar una excepción que no aparezca en la ventana Configuración de excepciones, seleccione Agregar (símbolo más). Introduzca un nombre para la excepción a inspeccionar. El nombre debe coincidir con el nombre completo de la excepción.

Configurar opciones de depuración de proyectos

De forma predeterminada, el depurador inicia el programa con el iniciador de Python estándar, sin argumentos de línea de comandos y ninguna otra ruta de acceso o condiciones especiales. Puede configurar las opciones de inicio de un proyecto de Python estableciendo las propiedades de depuración.

• Para acceder a las propiedades de depuración de un proyecto, haga clic con el botón derecho en el proyecto de Python en el Explorador de Soluciones, seleccione Propiedadesy luego seleccione la pestaña Depurar.

  

En las secciones siguientes se describen las propiedades específicas.

Definición del comportamiento de inicio

En la siguiente tabla se enumeran los valores posibles para la propiedad modo de inicio. Use esta propiedad para definir el comportamiento de inicio del depurador.

Valor	Descripción
Iniciador estándar de Python	Use el código de depuración escrito en Python portátil compatible con CPython, IronPython y variantes como Stackless Python. Esta opción proporciona la mejor experiencia para depurar código de Python puro. Cuando te conectas a un proceso de python.exe en ejecución, se usa el iniciador especificado en esta propiedad. Este iniciador también proporciona depuración en modo mixto para CPython, lo que le permite pasar sin problemas entre el código C/C++ y el código Python.
Iniciador web	Ejecute su navegador predeterminado al iniciar el sistema y habilite la depuración de plantillas. Para obtener más información, consulte la sección Depuración de plantillas web.
Iniciador web de Django	Implemente un comportamiento idéntico a la propiedad del iniciador web de, pero para un entorno de Django. Use esta opción solo con fines de compatibilidad con versiones anteriores.
Iniciador de IronPython (.NET)	Usa el depurador de .NET, que solo funciona con IronPython, pero permite hacer pasos entre cualquier proyecto de lenguaje .NET, incluidos C# y Visual Basic. Este iniciador se usa si se asocia a un proceso de .NET en ejecución que hospeda IronPython.

Definición del comportamiento de ejecución

En la tabla siguiente se describen las propiedades que puede establecer para configurar el comportamiento en ejecución del depurador.

Propiedad	Descripción
Rutas de búsqueda	Especifique las rutas de búsqueda de archivos y carpetas que Visual Studio usa para el proyecto. Estos valores coinciden con los elementos que se muestran en el nodo Rutas de búsqueda del proyecto en el Explorador de soluciones . Aunque puede especificar rutas de acceso de búsqueda en este cuadro de diálogo, puede ser más fácil usar Explorador de soluciones, donde puede examinar carpetas y convertir automáticamente rutas de acceso al formulario relativo.
Argumentos de script	Defina los argumentos que se van a agregar al comando que Visual Studio usa para iniciar el script y aparezca después del nombre de archivo del script. El primer elemento que aparece en el valor está disponible para el script como sys.argv[1], el segundo como sys.argv[2], etc.
Argumentos del intérprete	Enumere los argumentos que se van a agregar a la línea de comandos del iniciador antes del nombre del script. Los argumentos comunes son -W ... para controlar advertencias, -O para optimizar ligeramente el programa y -u para usar E/S no almacenada en búfer. Es probable que los usuarios de IronPython usen este campo para pasar opciones de -X, como -X:Frames o -X:MTA.
Ruta del Intérprete	Identifique una ruta de acceso del intérprete para invalidar la ruta de acceso asociada al entorno actual. El valor puede ser útil para iniciar el script con un intérprete no estándar.
Variables de Entorno	Use esta propiedad para agregar entradas del formulario <NAME>=\<VALUE>. Visual Studio aplica el valor de esta propiedad en último lugar, por encima de cualquier variable de entorno global existente, y después de que PYTHONPATH se establezca de acuerdo con la configuración Rutas de búsqueda. Como resultado, esta configuración se puede usar para invalidar manualmente cualquiera de esas otras variables.

Trabajar con ventanas interactivas

Existen dos ventanas interactivas que puede usar durante una sesión de depuración: la ventana Inmediato estándar de Visual Studio y la ventana Interactiva de depuración de Python.

Abrir la ventana Inmediata

Puede usar la ventana estándar de Visual Studio Inmediato para evaluar rápidamente las expresiones de Python e inspeccionar o asignar variables en el programa en ejecución. Para obtener más información, consulte Ventana Inmediato.

• Para abrir la ventana Immediato, seleccione Depurar>Windows>Immediato. También puede usar el método abreviado de teclado Ctrl+Alt+I.

Abra la ventana interactiva de depuración

La ventana Interactiva de depuración de Python ofrece un entorno enriquecido con toda la experiencia Interactiva REPL disponible mientras se depura, incluyendo la escritura y ejecución de código. Esta ventana se conecta automáticamente a cualquier proceso iniciado en el depurador mediante el iniciador de Python estándar, incluidos los procesos asociados a través de Depurar>Asociar al proceso. Sin embargo, esta ventana no está disponible cuando se usa la depuración de C/C++ en modo mixto.

• Para utilizar la ventana Depuración interactiva, seleccione Depurar>Windows>Depuración interactiva de Python (Mayús+Alt+I).

  

La ventana interactiva de depuración admite metacomandos especiales además de los comandos REPL estándar , según se describe en la tabla siguiente.

Comando	Descripción
$continue, $cont, $c	Empiece a ejecutar el programa desde la instrucción actual.
$down, $d	Baja el marco actual un nivel en el seguimiento de la pila.
$frame	Muestra el identificador de marco actual.
$frame	Cambie el marco actual al identificador de marco especificado. - Requiere un argumento <id. de marco>.
$load	Cargue los comandos desde el archivo y ejecútelos hasta completarlos.
$proc	Muestra el identificador de proceso actual.
$proc	Cambie el proceso actual al identificador de proceso especificado. - Requiere un argumento <id. de proceso>.
$procs	Enumere los procesos que se están depurando actualmente.
$stepin, $step, $s	Ir a la siguiente llamada de función, si es posible.
$stepout, $return, $r	Salga de la función actual.
$stepover, $until, $unt	Recorra paso a paso la siguiente llamada de función.
$thread	Muestra el identificador del subproceso actual.
$thread	Cambie el hilo actual al ID de hilo especificado. - Requiere un argumento <id. de subrpoceso>.
$threads	Enumere los subprocesos que se están depurando actualmente.
$up, $u	Sube el marco actual un nivel en el seguimiento de la pila.
$where, $w, $bt	Enumere los marcos del subproceso actual.

Las ventanas del depurador estándar, como Procesos, Subprocesos, y Pila de llamadas, no se sincronizan con la ventana Interactiva de depuración. Si cambia el proceso activo, el subproceso o el marco en la ventana de Depuración interactiva, las otras ventanas del depurador no se verán afectadas. Del mismo modo, el cambio del marco, subproceso o proceso activo en las otras ventanas del depurador no afecta a la ventana Interactiva de depuración.

Usar el depurador heredado

En función de la configuración del entorno, es posible que tenga que usar el depurador heredado:

• Visual Studio 2017, versión 15.7 y versiones anteriores con Python 2.6, 3.1 a 3.4 o IronPython
• Visual Studio 2019, versión 16.5 y posteriores, con Python 2.6, 3.1 a 3.4 o IronPython
• ptvsd 3.x y versiones anteriores de 4.x

El depurador heredado es la configuración predeterminada en Visual Studio 2017 versión 15.7 y anteriores.

• Para usar el depurador heredado, seleccione Herramientas>Opciones, expanda las opciones Python>Depuración y seleccione la opción Usar depurador heredado.

Compatibilidad con versiones anteriores de Visual Studio o Python

Visual Studio 2017 versión 15.8 y versiones posteriores usan un depurador basado en ptvsd versión 4.1 y posteriores. Visual Studio 2019 versión 16.5 y versiones posteriores usan un depurador basado en debugpy. Estas dos versiones del depurador son compatibles con Python 2.7 o Python 3.5 y versiones posteriores.

Si ejecuta una de estas versiones de Visual Studio, pero usa Python 2.6, 3.1 a 3.4 o IronPython, Visual Studio muestra el error, Debugger no admite este entorno de Python:

Cuando Visual Studio notifica este error de entorno, debe usar el depurador heredado.

Compatibilidad con versiones anteriores de ptvsd

Si usa una versión anterior de ptvsd en el entorno actual (por ejemplo, una versión anterior de 4.0.x o una versión 3.x necesaria para la depuración remota), Visual Studio podría mostrar un error o una advertencia.

Si el entorno usa ptvsd 3.x, Visual Studio muestra el error paquete Debugger no se pudo cargar:

La advertencia El paquete del depurador está obsoleto aparece cuando se ha usado una versión anterior a 4.x de ptvsd:

Cuando Visual Studio notifica estos errores de entorno, debe usar el depurador heredado.

Importante

Aunque puede optar por omitir la advertencia de algunas versiones de ptvsd, Es posible que Visual Studio no funcione correctamente.

Administración de la instalación de ptvsd

Siga estos pasos para administrar la instalación de ptvsd:

1. En la ventana entornos de Python, vaya a la pestaña Paquetes.

2. Escriba ptvsd en el cuadro de búsqueda y examine la versión instalada de ptvsd:

   

3. Si la versión es inferior a la 4.1.1a9 (la versión agrupada con Visual Studio), seleccione la X a la derecha del paquete para desinstalar la versión anterior. A continuación, Visual Studio usa su versión agrupada. (También puede desinstalar desde PowerShell mediante el comando pip uninstall ptvsd).

4. Como alternativa, puede actualizar el paquete ptvsd a su versión más reciente siguiendo las instrucciones en la sección titulada Solucionar problemas de escenarios de depuración.

Solucionar problemas en escenarios de depuración

En los escenarios siguientes se describen otras opciones de solución de problemas para la configuración de depuración.

Actualización de ptvsd para Visual Studio 2019

Si tiene problemas con el depurador en Visual Studio 2019 versión 16.4 y anteriores, actualice primero la versión del depurador de la siguiente manera:

1. En la ventana entornos de Python, vaya a la pestaña Paquetes.

2. Escriba ptvsd --upgrade en el cuadro de búsqueda y seleccione Ejecutar comando: pip install ptvsd --upgrade. (También puede usar el mismo comando desde PowerShell).

   

   Si los problemas persisten, abra un problema en el repositorio de GitHub de PTVS.

   Nota

   Para Visual Studio 2019, versión 16.5 y posteriores, debugpy forma parte de la carga de trabajo de Python de Visual Studio y se actualiza junto con Visual Studio.

Habilitación del registro del depurador

En el curso de investigar un problema del depurador, Microsoft puede pedirle que habilite y recopile registros del depurador para ayudar en el diagnóstico.

Los pasos siguientes habilitan la depuración en la sesión actual de Visual Studio:

1. Para abrir una ventana de comandos en Visual Studio, seleccione Ver>Otras ventanas>Ventana de comandos.

2. Escriba el siguiente comando:

   DebugAdapterHost.Logging /On /OutputWindow
   

3. Inicie la depuración y siga los pasos necesarios para reproducir su problema. Durante este tiempo, los registros de depuración aparecen en la ventana Salida bajo Registro del host de adaptador de depuración. Después, puede copiar los registros de esa ventana y pegarlos en un problema de GitHub, correo electrónico, etc.

   

4. Si Visual Studio deja de responder o no puede acceder a la ventana Salida, reinicie Visual Studio, abra una ventana de comandos y escriba el siguiente comando:

   DebugAdapterHost.Logging /On
   

5. Inicie la depuración y reproduzca el problema de nuevo. Los registros del depurador se encuentran en %temp%\DebugAdapterHostLog.txt.

Contenido relacionado

• Depurar en Visual Studio
• Mixed-mode Python/C++ debugging (Depuración en modo mixto Python/C++)
• Symbols for mixed-mode debugging (Símbolos de depuración en modo mixto)