Depurar código Python no Visual Studio

Artigo
04/18/2024

O Visual Studio proporciona uma experiência de depuração abrangente para Python. Neste artigo, você explora como anexar o depurador a processos em execução e avaliar expressões nas janelas Observação e Imediata. No depurador, você pode inspecionar variáveis locais, usar pontos de interrupção, instruções step in/out/over, Definir Próxima Instrução e muito mais.

Para obter informações de depuração específicas do cenário, consulte estes artigos:

Pré-requisitos

Ter o Visual Studio instalado e compatível com cargas de trabalho do Python. Para obter mais informações, confira Instalar o suporte ao Python no Visual Studio.
Código Python para usar com o depurador.

Depurar código com ou sem projeto

Se você quiser controlar o ambiente Python e argumentos, primeiro crie um projeto para seu código. Você pode criar um projeto com o modelo de projeto Com base em um código existente do Python. Para obter mais informações, consulte o Crie um projeto a partir de arquivos de código Python existentes.

Porém, você não precisa de um arquivo de projeto ou solução no Visual Studio para depurar seu código Python. Para depurar código em um arquivo Python autônomo, abra o arquivo no Visual Studio e selecione Depurar>Iniciar depuração. O Visual Studio inicia o script com o ambiente padrão global e sem argumentos. Depois, você tem suporte de depuração completo para seu código. Para saber mais, veja Ambientes do Python.

Explorar a depuração básica

O fluxo de trabalho básico de depuração envolve a definição de pontos de interrupção, a execução do código em etapas, a inspeção de valores e o tratamento de exceções. Você pode iniciar uma sessão de depuração selecionando Debug>Iniciar depuração ou use o atalho de teclado F5. Para um projeto, essas ações iniciam o arquivo de inicialização com o ambiente ativo do projeto e quaisquer argumentos de linha de comando ou caminhos de pesquisa especificados para Propriedades do Projeto. Para configurar as propriedades, consulte Definir opções de depuração de projeto.

Definir o arquivo de inicialização do projeto

O arquivo de inicialização de um projeto é mostrado em negrito no Gerenciador de Soluções. Você pode escolher qual arquivo usar como o arquivo de inicialização.

Para especificar um arquivo de projeto como o arquivo de inicialização, clique com o botão direito do mouse no arquivo e selecione Definir como item de inicialização.

No Visual Studio 2017 versão 15.6 e posterior, você verá um alerta caso não tenha um conjunto de arquivos de inicialização especificado. Versões anteriores do Visual Studio podem abrir uma janela Saída com o interpretador Python em execução ou a janela Saída abre e fecha brevemente.

Especificar o ambiente ativo

Se você estiver usando um arquivo de projeto, o depurador sempre iniciará com o ambiente Python ativo para o projeto. Você pode mudar o ambiente ativo atual. Para obter mais informações, confira Selecionar um ambiente Python para um projeto.

Se você estiver depurando um arquivo de código Python autônomo, o Visual Studio iniciará o script com o ambiente padrão global sem argumentos.

Definir Pontos de Interrupção

Os pontos de interrupção interrompem a execução de código em um ponto marcado, para que você possa inspecionar o estado do programa.

Alguns pontos de interrupção no Python podem ser surpreendentes para desenvolvedores que trabalharam com outras linguagens de programação. No Python, todo o arquivo é um código executável, para que o Python execute o arquivo quando ele é carregado para processar as definições de classe ou de função de nível superior. Se um Ponto de interrupção estiver definido, você poderá descobrir que o depurador está interrompendo uma declaração de classe parcialmente. Esse comportamento é correto, mesmo que às vezes seja surpreendente.

Para definir um Ponto de interrupção, selecione na margem esquerda do editor de código ou clique com o botão direito em uma linha de código e selecione Ponto de interrupção>Insert Breakpoint. Um ponto vermelho é exibido em cada linha com Ponto de interrupção.
Para remover um Ponto de interrupção, selecione o ponto vermelho ou clique com o botão direito na linha de código e selecione Ponto de interrupção>Excluir Ponto de interrupção. Você também pode desabilitar um Ponto de interrupção selecionando o ponto vermelho e selecionando Ponto de interrupção>Desabilitar Ponto de interrupção.

Definir condições e ações

É possível personalizar as condições nas quais um ponto de interrupção é disparado, como a interrupção somente quando uma variável é configurada para um determinado valor ou intervalo de valores.

Para definir condições, clique com o botão direito no ponto vermelho do ponto de interrupção e selecione Condições. A caixa de diálogo Configurações do ponto de interrupção é aberta.

Na caixa de diálogo, você pode adicionar várias condições e criar expressões condicionais com o código Python. Para obter detalhes completos sobre esse recurso no Visual Studio, confira Condições de ponto de interrupção.
Você também tem as opções para definir Ações para um Ponto de interrupção. Você pode criar uma mensagem para registrar na janela Saída e, opcionalmente, especificar para continuar a execução automaticamente.

Registrar uma mensagem cria o que um tracepoint que não adiciona código de log ao aplicativo diretamente.

Dependendo de como você configura as condições e ações para um ponto de interrupção, o ícone vermelho na margem esquerda muda para indicar suas configurações. Você pode ver a forma do ponto, um cronômetro ou um diamante.

Percorrer o código

Quando o Visual Studio interrompe a execução de código em um ponto de interrupção, há diversos comandos que você pode usar para percorrer seu código ou executar blocos de código antes de quebrar novamente. Os comandos estão disponíveis em alguns lugares no Visual Studio, incluindo a barra de ferramentas Depurador, o menu Depurar, o menu de contexto do botão direito do mouse no editor de código e pelos atalhos de teclado.

Depois, a tabela resume esses comandos e fornece o atalho de teclado:

Comando	Atalho	Descrição
Continuar	F5	Execute o código até chegar ao próximo ponto de interrupção.
Intervir	F11	Execute a próxima instrução e parada. Se a próxima instrução for uma chamada a uma função, o depurador parará na primeira linha da função chamada.
Contornar	F10	Execute a próxima instrução, incluindo fazer uma chamada a uma função (executando todo o código) e aplicar qualquer valor retornado. Este comando permite a depuração parcial permite ignorar facilmente as funções que não precisam ser depuradas.
Sair	Shift+F11	Execute o código até o final da função atual e, depois, vá para a instrução de chamada. Esse comando é útil quando não é necessário depurar o restante da função atual.
Executar até o cursor	Ctrl+F10	Execute o código até a localização do cursor no editor. Esse comando permite ignorar facilmente um segmento de código que não precisa ser depurado.
Definir Próxima Instrução	Ctrl+Shift+F10	Altere o ponto de execução atual no código para a localização atual do cursor. Esse comando permite omitir a execução de um segmento de código, como nos casos em que você sabe que o código tem uma falha ou produz um efeito colateral indesejado.
Mostrar Próxima Instrução	Alt+Num+\	Volte à próxima instrução a ser executada no código. Esse comando ajuda a localizar o lugar no código onde o depurador está parado.

Inspecionar e modificar valores

Ao interromper a execução do código no depurador, você poderá inspecionar e modificar os valores das variáveis. Use também a janela Inspeção para monitorar variáveis individuais e expressões personalizadas. Para obter mais informações, consulte Inspecionar variáveis.

Para exibir um valor usando o recurso DataTips durante a depuração, basta passar o mouse sobre qualquer variável no editor. Você pode selecionar o valor da variável para alterá-lo:
Para usar a janela Automáticos, selecione Depurar>Windows>Automáticos. Esta janela contém variáveis e expressões próximas da instrução atual. Clique duas vezes na coluna do valor ou selecione e pressione F2 para editar o valor:

Para obter mais informações sobre como usar a janela Automáticos, consulte Inspecionar variáveis nas janelas Automáticos e Locais.
Para usar a janela Locais, selecione Depurar>Windows>Locais. Esta janela mostra todas as variáveis que estão no escopo atual, que podem ser editadas novamente:

Para obter mais informações sobre como usar a janela Locais, consulte Inspecionar variáveis nas janelas Automáticos e Locais.
Para usar as janelas Assistir, selecione Depurar>Windows>Assistir>Assistir 1-4. Essa opção permite que você insira expressões arbitrárias do Python e veja os resultados. As expressões são reavaliadas para cada etapa:

Para obter mais informações sobre como usar a janela Inspeção, consulte Definir uma inspeção em variáveis usando as janelas Inspeção e QuickWatch.
Para inspecionar um valor de cadeia de caracteres, selecione Exibir (lupa) no lado direito da entrada Valor. Os tipos str, unicode, bytes, e bytearray estão todos disponíveis para inspeção.

O menu suspenso Exibir mostra quatro opções de visualização: Texto, HTML, XML ou JSON.

Depois de selecionar uma visualização, uma caixa de diálogo pop-up exibe o valor da cadeia de caracteres sem aspas de acordo com o tipo selecionado. Você pode exibir a cadeia de caracteres com a quebra automática e rolagem, realce de sintaxe e exibições em árvore. Essas visualizações podem ajudar a depurar problemas de cadeias de caracteres longas e complexas.

Exibir exceções

Se ocorrer um erro no programa durante a depuração, mas você não tiver um manipulador de exceção para ele, o depurador interromperá no ponto da exceção:

Quando ocorrer um erro, você pode inspecionar o estado atual do programa, incluindo a pilha de chamadas. Porém, se você percorrer o código, o processo de depuração continuará lançando a exceção até que ela seja tratada ou o programa seja encerrado.

Para ver uma exibição expandida de exceções, selecione Depurar>Windows>Configurações de exceção.

Na janela Configurações de exceções, a caixa de seleção ao lado de uma exceção controla se o depurador always quebra quando essa exceção é gerada.
Para quebrar com mais frequência para uma exceção específica, marque a caixa de seleção ao lado da exceção na janela Configurações de exceção.
Por padrão, a maioria das exceções interromperá quando não for possível encontrar um manipulador de exceção no código-fonte. Para alterar esse comportamento, clique com o botão direito do mouse em qualquer exceção e modifique a opção Continuar Quando Não For Tratada no Código do Usuário. Para quebrar com menos frequência para a exceção, desmarque a opção.
Para configurar uma exceção que não aparece na janela Configurações de Exceção, selecione Adicionar (símbolo de adição). Digite um nome para a exceção a ser observada. O nome deve corresponder ao nome completo da exceção.

Configurar opções de depuração de projeto

Por padrão, o depurador inicia o programa com o inicializador padrão do Python, sem argumentos de linha de comando e sem nenhum outro caminho ou condição especial. Você pode configurar as opções de inicialização para um projeto Python ao definir as propriedades de depuração.

Para acessar as propriedades de depuração de um projeto, clique com o botão direito do mouse no projeto Python no Gerenciador de soluções, selecione Propriedades, e selecione a guia Depurador.

As seções seguintes descrevem as propriedades específicas.

Definir comportamento de inicialização

A tabela a seguir lista os valores possíveis para a propriedade Modo de inicialização. Use esta propriedade para definir o comportamento de inicialização do depurador.

Valor	Descrição
Inicializador padrão do Python	Use o código de depuração escrito no Python portátil que é compatível com o CPython, IronPython e variantes como o Stackless Python. Essa opção fornece a melhor experiência de depuração de código puro do Python. Quando você o anexa a um processo `python.exe` em execução, o Launcher especificado nessa propriedade é usado. Esse iniciador também fornece a depuração de modo misto para o CPython, que permite a execução em etapas direta entre o código do C/C++ e o código do Python.
Inicializador da Web	Inicie o navegador padrão na inicialização e habilita a depuração de modelos. Para mais informações, consulte a seção Depuração de modelos da Web.
Inicializador da Web do Django	Implemente um comportamento idêntico à propriedade Web launcher para um ambiente Django. Use esta opção somente para fins de compatibilidade com versões anteriores.
Inicializador do IronPython (.NET)	Use o depurador do .NET, que funciona somente com o IronPython, mas que permite a execução em etapas entre qualquer projeto de linguagem .NET, incluindo C# e Visual Basic. Esse inicializador é usado se você se anexar a um processo em execução do .NET que hospeda o IronPython.

Definir comportamento de execução

A tabela a seguir descreve as propriedades que você pode definir para configurar o comportamento de execução do depurador.

Propriedade	Descrição
Caminhos de Pesquisa	Especifique os caminhos de pesquisa de arquivo e pasta que o Visual Studio usa para o seu projeto. Esses valores correspondem os itens mostrados no nó Caminhos de Pesquisa do projeto no Gerenciador de Soluções. Embora você possa especificar caminhos de pesquisa nessa caixa de diálogo, pode ser mais fácil usar o Gerenciador de Soluções, onde você pode navegar nas pastas e converter automaticamente os caminhos em formato relativo.
Argumentos do script	Defina os argumentos a serem adicionados ao comando que o Visual Studio usa para iniciar seu script e aparecem após o nome do arquivo do seu script. O primeiro item listado no valor está disponível para o script como `sys.argv[1]`, o segundo como `sys.argv[2]` e assim por diante.
Argumentos do interpretador	Liste os argumentos para adicionar à linha de comando do inicializador antes do nome do script. Os argumentos comuns aqui são `-W ...` para controlar avisos, `-O` para otimizar ligeiramente o programa e `-u` para usar o E/S não armazenado em buffer. Provavelmente, os usuários do IronPython usarão esse campo para passar opções `-X`, como `-X:Frames` ou `-X:MTA`.
Caminho do Interpretador	Identifique um caminho de intérprete para substituir o caminho associado ao ambiente presente. O valor poderá ser útil para iniciar o script com um interpretador não padrão.
Variáveis de Ambiente	Use essa propriedade para adicionar entradas do formato `<NAME>=\<VALUE>`. O Visual Studio aplica esse valor de propriedade por último, sobre qualquer variável de ambiente global existente, e depois `PYTHONPATH` é definido de acordo com a configuração Caminhos de pesquisa. Como resultado, essa configuração pode ser usada para substituir manualmente qualquer uma destas outras variáveis.

Trabalhe com janelas interativas

Há duas janelas interativas que podem ser usadas durante uma sessão de depuração: a janela padrão do Visual Studio e a janela Imediata e a janela Interativa de Depuração do Python.

Abrir a janela Imediata

Você pode usar a janela padrão Imediata do Visual Studio para avaliar rapidamente expressões Python e inspecionar ou atribuir variáveis em seu programa em execução. Para obter mais informações, consulte Janela Imediata.

Para abrir a janela Immediate, selecione Depurar>Windows>Imediata. Você também pode usar o atalho de teclado Ctrl+Alt+I.

Abra a Janela Interativa de Depuração

A Janela Interativa de Depuração oferece um ambiente rico com a experiência completa REPL Interativo interativo disponível durante a depuração, incluindo a gravação e execução de código. Essa janela se conecta automaticamente a qualquer processo iniciado no depurador usando o inicializador Padrão do Python, incluindo os processos anexados por meio de Depurar>Anexar ao Processo. Porém, esta janela não está disponível ao usar a depuração C/C++ de modo misto.

Para usar a janela Interativa de Depuração, selecione Depurar>Windows>Interativa de Depuração do Python (Shift+Alt+I).

A janela Interativa de Depuração suporta meta-comandos especiais além do comandos REPL padrão, conforme descrito na tabela a seguir:

Comando	Descrição
`$continue`, `$cont`, `$c`	Inicie a execução do programa da instrução atual.
`$down`, `$d`	Move o quadro atual um nível para baixo no rastreamento de pilha.
`$frame`	Exiba a ID de quadro atual.
`$frame`	Mude a ID de quadro atual para a ID de quadro especificada. - Requer um argumento de <ID de quadro>.
`$load`	Carregue comandos do arquivo e os executa até a conclusão.
`$proc`	Exiba a ID de processo atual.
`$proc`	Mude a ID de processo atual para a ID de processo especificada. - Requer um argumento de <ID de processo>.
`$procs`	Liste os processos que estão sendo depurados no momento.
`$stepin`, `$step`, `$s`	Intervenha na próxima chamada de função, se possível.
`$stepout`, `$return`, `$r`	Encaminhe-se para fora da função atual.
`$stepover`, `$until`, `$unt`	Depure parcialmente a próxima chamada de função.
`$thread`	Exiba a ID de thread atual.
`$thread`	Mude a ID de thread atual para a ID de thread especificada. - Requer um argumento de <ID de thread>.
`$threads`	Liste os threads que estão sendo depurados no momento.
`$up`, `$u`	Move o quadro atual um nível para cima no rastreamento de pilha.
`$where`, `$w`, `$bt`	Liste os quadros do thread atual.

As janelas padrão do depurador, como Processos, Threads e Pilha de Chamadas, não são sincronizadas com a janela Interativa de Depuração. Se você alterar o processo, thread ou quadro ativo no Debug Interactive não afeta as outras janelas do depurador. Da mesma forma, a alteração do processo, do thread ou do quadro ativo nas outras janelas do depurador não afeta a janela Interativa de Depuração.

Usar o depurador herdado

Dependendo da configuração do ambiente, talvez seja preciso usar o depurador herdado:

O Visual Studio 2017 versão 15.7 e anterior com Python 2.6, 3.1 a 3.4 ou IronPython
O Visual Studio 2019 versão 16.5 e posterior com Python 2.6, 3.1 a 3.4 ou IronPython
ptvsd 3.x e versões anteriores 4.x

O depurador herdado é o padrão no Visual Studio 2017 versão 15.7 e anterior.

Para usar o depurador herdado, selecione Ferramentas>Opções, expanda as opções Python>Depurando e selecione a opção Usar depurador legado.

Suporte a versões mais antigas do Visual Studio ou Python

O Visual Studio 2017 versão 15.8 e posteriores usam um depurador com base no ptvsd versão 4.1 e superior. O Visual Studio 2019 versão 16.5 e posteriores usam um depurador baseado no debugpy. Essas duas versões do depurador são compatíveis com o Python 2.7 ou Python 3.5 e superiores.

Se você estiver executando uma dessas versões do Visual Studio, mas estiver usando Python 2.6, 3.1 a 3.4 ou IronPython, o Visual Studio mostrará o erro O depurador não dá suporte a este ambiente do Python:

Quando o Visual Studio informa esse erro de ambiente, você deve usar o depurador herdado.

Suporte a versões ptvsd mais antigas

Se você tiver usando uma versão mais antiga do ptvsd no ambiente atual (como uma versão 4.0.x anterior ou uma versão 3.x necessária para a depuração remota), o Visual Studio poderá mostrar um erro ou aviso.

Se seu ambiente usa ptvsd 3.x, Visual Studio mostra o erro Não foi possível carregar o pacote do depurador:

O aviso O pacote do depurador está desatualizado será exibido se você estiver usando uma versão 4.x anterior do ptvsd:

Quando o Visual Studio informa esses error de ambiente, você deve usar o depurador herdado.

Importante

Embora você possa optar por ignorar o aviso em algumas versões do ptvsd, o Visual Studio pode não funcionar corretamente.

Gerenciar a instalação do ptvsd

Siga estes passos para gerenciar sua instalação ptvsd:

Na janela Ambientes do Python, acesse a guia Pacotes.
Insira ptvsd na caixa de pesquisa e examine a versão do ptvsd instalada:
Se a versão for inferior à 4.1.1a9 (a versão empacotada com o Visual Studio), selecione o X à direita do pacote para desinstalar a versão mais antiga. Assim, o Visual Studio passará a usar a versão empacotada. Você também pode desinstalar do PowerShell usando o comando pip uninstall ptvsd.
Como alternativa, você pode atualizar o pacote ptvsd para a última versão seguindo as instruções na seção Solução de problemas.

Solução de problemas de cenários de depuração

Os cenários a seguir descrevem outras opções de solução de problemas para a configuração de depuração.

Atualizar o ptvsd para Visual Studio 2019

Se você tiver problemas com o depurador no Visual Studio 2019 versão 16.4 e anterior, atualize primeiro sua versão do depurador da seguinte maneira:

Na janela Ambientes do Python, acesse a guia Pacotes.
Insira ptvsd --upgrade na caixa de pesquisa, em seguida, selecione Executar o comando: pip install ptvsd --upgrade. (Você também pode usar o mesmo comando no PowerShell).

Se o problema persistir, registre o problema no Repositório GitHub do PTVS.

Observação

No Visual Studio 2019 versão 16.5 e posteriores, a depuração faz parte da carga de trabalho do Python no Visual Studio e é atualizada junto com o Visual Studio.

Habilitar registro em log do depurador

Ao investigar o problema do depurador, a Microsoft pode solicitar que você habilite e colete logs de depurador para ajudar no diagnóstico.

As seguintes etapas habilitam a depuração na sessão atual do Visual Studio:

Abra uma janela de comando no Visual Studio selecionando Visualizar>Outros Windows>Janela de Comando.

Insira o seguinte comando:

DebugAdapterHost.Logging /On /OutputWindow

Inicie a depuração e veja todas as etapas necessárias para reproduzir o problema. Durante esse tempo, os logs de depuração aparecem na janela Saída em Log de Host do Adaptador de Depuração. Depois, você poderá copiar os logs dessa janela e colá-los em um problema do GitHub, em um email etc.
Se o Visual Studio parar de responder ou se não for possível acessar a janela Saída, reinicie o Visual Studio, abra uma janela de comando e digite o seguinte comando:
```
DebugAdapterHost.Logging /On
```
Inicie a depuração e reproduza o problema novamente. Os logs do depurador ficam em %temp%\DebugAdapterHostLog.txt.

Depurar código Python no Visual Studio

Pré-requisitos

Depurar código com ou sem projeto

Explorar a depuração básica