Criar e gerenciar ambientes Python no Visual Studio

Um ambiente de Python é um contexto em que você executa código Python e inclui ambientes globais, virtuais e conda. Um ambiente é composto por um interpretador, uma biblioteca (normalmente a Biblioteca Padrão do Python) e um conjunto de pacotes instalados. Juntos, esses componentes determinam constructos de linguagem e sintaxe válidos, qual funcionalidade do sistema operacional pode ser acessada e quais pacotes podem ser usados.

No Visual Studio no Windows, use a janela Ambientes do Python, conforme descrito neste artigo, para gerenciar ambientes e selecionar um como o padrão para novos projetos. Outros aspectos dos ambientes são encontrados nos seguintes artigos:

• Para qualquer projeto, você pode selecionar um ambiente específico em vez de usar o padrão.

• Para obter detalhes de como criar e usar ambientes virtuais para projetos Python, confira Usar ambientes virtuais.

• Se desejar instalar pacotes em um ambiente, confira a referência da guia Pacotes.

• Para instalar outro interpretador do Python, confira Instalar interpretadores do Python. Em geral, se você baixar e executar um instalador de uma distribuição principal do Python, o Visual Studio detectará que a nova instalação e o ambiente aparecem na janela Ambientes do Python e podem ser selecionados para projetos.

Observação

Você pode gerenciar ambientes de código Python abertos como uma pasta ao selecionar Arquivo>Abrir>Pasta. A barra de ferramentas do Python permite alternar entre todos os ambientes detectados e também adicionar um novo ambiente. As informações de ambiente são armazenadas no arquivo PythonSettings.json na pasta .vs do espaço de trabalho.

Pré-requisitos

• Ter uma carga de trabalho do Python instalada.

Caso esteja conhecendo agora o Python no Visual Studio, confira os seguintes artigos para obter informações gerais:

• Trabalhar com o Python no Visual Studio
• Instalar o suporte de Python no Visual Studio

A janela Ambientes do Python

Os ambientes conhecidos pelo Visual Studio são exibidos na janela Ambientes Python. Para abrir a janela, use um dos seguintes métodos:

• Escolha Exibir>Outras Janelas>Ambientes do Python.
• Clique com o botão direito do mouse no nó Ambientes do Python de um projeto no Gerenciador de Soluções e escolha Exibir Todos os Ambientes do Python.

A janela Ambientes do Python é exibida com o Gerenciador de Soluções no Visual Studio:

O Visual Studio procura por ambientes globais instalados usando o Registro (seguindo o PEP 514), junto com os ambientes virtuais e os ambientes do Conda (confira Tipos de ambientes). Se um ambiente esperado na lista não for exibido, confira Manually identify an existing environment (Identificar manualmente um ambiente existente).

Quando você escolhe um ambiente da lista, o Visual Studio exibe diversas propriedades e comandos para esse ambiente na guia Visão Geral da janela Ambientes do Python , como o local do interpretador. Os comandos na parte inferior da guia Visão Geral abrem um prompt de comando com o interpretador em execução. Para obter mais informações, confira Referência de guias da janela Ambientes do Python – Visão Geral.

Use a lista suspensa embaixo da lista de ambientes para alternar para diferentes guias como Pacotes e IntelliSense. Essas guias também são descritas na Referência de guias da janela Ambientes do Python.

A seleção de um ambiente não altera sua relação com nenhum projeto. O ambiente padrão, mostrado em negrito na lista, é aquele que o Visual Studio usa para os novos projetos. Para usar um ambiente diferente com os novos projetos, use o comando Tornar este ambiente o padrão para novos projetos. No contexto de um projeto, sempre é possível selecionar um ambiente específico. Para obter mais informações, confira Selecionar um ambiente para um projeto.

À direita de cada ambiente listado, há um controle que abre uma janela Interativa nesse ambiente. (No Visual Studio 2017 15.5 e versões anteriores, aparece outro controle que atualiza o banco de dados do IntelliSense para esse ambiente. Para obter detalhes sobre o banco de dados, consulte Referência de guias da janela Ambientes do Python.)

Dica

Ao expandir a janela Ambientes do Python até o tamanho suficiente, você obtém uma exibição mais completa de seus ambientes, a qual pode ser mais conveniente para trabalhar.

Observação

Embora o Visual Studio respeite a opção de pacotes de site do sistema, ele não fornece uma maneira de alterá-lo no próprio Visual Studio.

E se nenhum ambiente aparecer?

Se não aparecer nenhum ambiente na janela Ambientes do Python, o Visual Studio não terá conseguido detectar nenhuma instalação do Python nos locais padrão. Talvez você tenha instalado o Visual Studio 2017 ou posterior, mas limpou todas as opções de interpretador nas opções do instalador para a carga de trabalho do Python. Da mesma forma, é possível que você tenha instalado o Visual Studio 2015 ou versões anteriores, mas não tenha instalado um interpretador manualmente. Para obter mais informações, confira Instalar interpretadores do Python.

Se você souber que tem um interpretador do Python no computador, mas o Visual Studio (qualquer versão) não conseguir detectá-lo, use o comando + Personalizado para especificar o local do interpretador manualmente. Para obter mais informações, confira como identificar manualmente um ambiente existente.

Tipos de ambientes

O Visual Studio pode trabalhar com ambientes globais, virtuais e do Conda.

Ambientes globais

Cada instalação do Python mantém o próprio ambiente global. Por exemplo, Python 2.7, Python 3.6, Python 3.7, Anaconda 4.4.0 e assim por diante. Para obter mais informações, confira Instalar interpretadores do Python.

Cada ambiente é composto pelo interpretador do Python específico, sua biblioteca padrão e por um conjunto de pacotes pré-instalados. Também contém todos os outros pacotes instalados enquanto o ambiente está ativado. A instalação de um pacote em um ambiente global o torna disponível para todos os projetos que usam esse ambiente. Se o ambiente estiver em uma área protegida do sistema de arquivos (em c:\Arquivos de Programas, por exemplo), a instalação de pacotes exigirá privilégios de administrador.

Os ambientes globais estão disponíveis para todos os projetos no computador. No Visual Studio, selecione um ambiente global como o padrão, que é usado para todos os projetos, a menos que você escolha especificamente um diferente para um projeto. Para obter mais informações, confira Selecionar um ambiente para um projeto.

Ambientes virtuais

Trabalhar em um ambiente global é uma maneira fácil de começar. Com o passar do tempo, os ambientes podem ficar confusos, com muitos pacotes diferentes instalados para projetos diferentes. Essa desordem pode dificultar o teste completo do aplicativo em relação a um conjunto específico de pacotes com versões conhecidas. No entanto, esse tipo de ambiente é o que você configuraria em um servidor de build ou servidor Web. Também poderão ocorrer conflitos quando dois projetos exigirem pacotes incompatíveis ou versões diferentes do mesmo pacote.

Por esses motivos, os desenvolvedores geralmente criam um ambiente virtual para um projeto. Um ambiente virtual é uma subpasta em um projeto que contém uma cópia de um interpretador específico. Se você ativa o ambiente virtual, todos os pacotes passam a ser instalados somente na subpasta desse ambiente. Ao executar um programa em Python dentro do ambiente virtual, você sabe que o programa será executado apenas nesses pacotes específicos.

O Visual Studio dá suporte direto para a criação de um ambiente virtual para um projeto. Caso você abra um projeto que contém um arquivo requirements.txt, o Visual Studio envia uma solicitação automática para criar um ambiente virtual e instalar essas dependências. O mesmo comportamento é visto ao criar um projeto com base em um modelo que inclui o arquivo requirements.txt.

A qualquer momento dentro de um projeto aberto, você pode criar um ambiente virtual. No Gerenciador de Soluções, expanda o nó do projeto, clique com o botão direito do mouse no nó Ambientes do Python e escolha Adicionar ambiente. Em Adicionar Ambiente, escolha Ambiente virtual. Para obter mais informações, confira Criar um ambiente virtual.

O Visual Studio também fornece um comando para gerar um arquivo requirements.txt em um ambiente virtual, tornando mais fácil recriar o ambiente em outros computadores. Para obter mais informações, confira Usar ambientes virtuais.

Ambientes do Conda

Você pode criar um ambiente do Conda usando a ferramenta conda, ou com o gerenciamento do Conda integrado no Visual Studio 2017 versão 15.7 ou posterior. Um ambiente do Conda exige Anaconda ou Miniconda. Essas plataformas são disponibilizadas pelo instalador do Visual Studio. Para obter mais informações, confira Instalar o suporte ao Python no Visual Studio.

1. Na janela Ambientes do Python (ou na barra de ferramentas Python), selecione Adicionar Ambiente para abrir a caixa de diálogo Adicionar ambiente.

2. Na caixa de diálogo Adicionar ambiente, selecione a guia Ambiente do Conda:

   

3. Configure os seguintes campos:

   Campo	Descrição
   Projeto	Identifica o projeto em que deseja criar um ambiente.
   Nome	Informa o nome para o ambiente do Conda.
   Adicionar pacotes de	Define como adicionar pacotes ao ambiente do Conda. - Arquivo de ambiente: escolha esta opção caso tenha um arquivo environment.yml que descreva suas dependências. Insira o nome do arquivo ou acesse (...) o local dele e selecione-o. - Um ou mais nomes de pacote do Anaconda: escolha esta opção caso queira listar um ou mais pacotes do Python ou versões do Python. A lista de pacotes instrui o conda a criar um ambiente de Python. Para instalar a versão mais recente do Python, use o comando python. Para instalar uma versão específica, utilize o comando python=,major>.<minor>, como em python=3.7. Você também pode usar o botão de pacote para selecionar as versões do Python e pacotes comuns de uma série de menus.
   Definir como ambiente atual	Depois que o ambiente for criado, ativa o novo ambiente no projeto selecionado.
   Definir como ambiente padrão para novos projetos	Define e ativa o ambiente do conda automaticamente em todos os novos projetos criados no Visual Studio. Essa opção é o mesmo que usar Tornar este o ambiente padrão para novos projetos na janela Ambientes do Python.
   Exibir na janela de ambientes do Python	Especifica se deve mostrar a janela Ambientes do Python depois de criar o ambiente.

   Importante

   Ao criar um ambiente do Conda, especifique pelo menos uma versão do Python ou um pacote do Python a fim de garantir que o ambiente contenha um tempo de execução do Python. É possível usar um arquivo environments.yml ou a lista de pacotes. Se você não informar essa especificação, o Visual Studio vai ignorar o ambiente. O ambiente não aparece em nenhum lugar na janela Ambientes do Python, nem está definido como ambiente atual de um projeto, nem está disponível como um ambiente global.

   Caso você crie um ambiente do Conda sem uma versão do Python, utilize o comando conda info para conferir os locais das pastas do ambiente do Conda. Depois, você poderá remover manualmente a subpasta do ambiente desse local.

4. Selecione Criar.

   É possível monitorar a criação do ambiente do Conda na janela Saída. Assim que criação for concluída, a saída exibirá algumas instruções da interface de linha de comando (CLI), como activate env:

   

5. No Visual Studio, é possível ativar um ambiente do Conda para um projeto da mesma forma que você ativaria qualquer outro ambiente. Para obter mais informações, confira Selecionar um ambiente para um projeto.

6. Para instalar mais pacotes no ambiente, utilize a guia Pacotes na janela Ambientes do Python .

Observação

Para conseguir os melhores resultados com um ambiente do Conda, utilize o Conda 4.4.8 ou versões posteriores. Lembre-se de que as versões do Conda são diferentes das versões do Anaconda. Você pode instalar versões adequadas do Miniconda (Visual Studio 2019 e Visual Studio 2022) e Anaconda (Visual Studio 2017) pelo instalador do Visual Studio.

Para ver a versão do Conda, na qual os ambientes do Conda são armazenados, bem como outras informações, execute o comando conda info em um prompt de comando do Anaconda (ou seja, um prompt de comando no qual o Anaconda está no caminho):

conda info

As pastas de ambiente do conda são exibidas da seguinte maneira:

       envs directories : C:\Users\user\.conda\envs
                          c:\anaconda3\envs
                          C:\Users\user\AppData\Local\conda\conda\envs

Como os ambientes do Conda não são armazenados com um projeto, eles se comportam da mesma forma que os ambientes globais. Por exemplo, a instalação de um novo pacote em um ambiente do Conda torna esse pacote disponível para todos os projetos que usam esse ambiente.

Para o Visual Studio 2017 versão 15.6 e anterior, você pode usar ambientes do Conda apontando-os manualmente, conforme descrito em Identificar manualmente um ambiente existente.

O Visual Studio 2017 versão 15.7 e posterior detecta ambientes do conda automaticamente e exibe-os na janela Ambientes do Python, conforme descrito na próxima seção.

Identificar manualmente um ambiente existente

Use as etapas a seguir para identificar um ambiente instalado em um local não padrão.

1. Na janela Ambientes do Python (ou na barra de ferramentas Python), selecione Adicionar Ambiente para abrir a caixa de diálogo Adicionar ambiente.

2. Na guia Ambiente existente da caixa de diálogo Adicionar ambiente, ajuste o campo Ambiente como <Personalizado>:

   

   Após selecionar o valor <Personalizado> , mais campos serão adicionados à caixa de diálogo.

3. Ajuste o campo Caminho do prefixo como o caminho do interpretador. É possível ajustar o campo acessando (...) o local do caminho.

   

4. Após escolher o caminho, os campos restantes serão preenchidos. Revise os valores e modifique o que for necessário. Quando terminar, selecione Adicionar.

Você também pode examinar e modificar detalhes do ambiente a qualquer momento na janela Ambientes do Python.

1. Na janela Ambientes do Python, selecione o ambiente e escolha a guia Configurar.

2. Depois de fazer alterações, selecione o comando Aplicar.

Também é possível remover um ambiente usando o comando Remover . Para obter mais informações, consulte a guia Configurar. Este comando não está disponível para ambientes com detecção automática.

Corrigir ou excluir ambientes inválidos

Se o Visual Studio encontra entradas do Registro para um ambiente, mas o caminho para o interpretador é inválido, a janela Ambientes do Python exibe o nome do ambiente em um formato de fonte riscada, conforme mostra a imagem a seguir:

Para corrigir um ambiente que você deseja manter, primeiro tente usar o processo Reparar do instalador desse ambiente. Grande parte dos instaladores inclui uma opção para reparar.

Modificar o registro para corrigir um ambiente

Se o ambiente do Python não tiver uma opção para reparar ou se você quiser remover um ambiente inválido, poderá usar as etapas a seguir para modificar o Registro diretamente. O Visual Studio atualiza automaticamente a janela Ambientes do Python quando você faz alterações no Registro.

1. Execute o executável regedit.exe para abrir o Editor do Registro.

2. Acesse a pasta do ambiente correspondente à sua configuração:

   Versão do Python	Pasta
   Versão de 64 bits	HKEY_LOCAL_MACHINE\SOFTWARE\Python or HKEY_CURRENT_USER\Software\Python
   Versão de 32 bits	HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Python
   IronPython	IronPython

3. Expanda a estrutura de nós de distribuições e versões do ambiente:

   Distribuição	Nó
   CPython	PythonCore><Nó da versão>
   Anaconda	ContinuumAnalytics><Nó da versão>
   IronPython	<Nó da versão>

4. Inspecione os valores no nó InstallPath:

   

   • Se o ambiente ainda existir no computador, altere o valor da entrada ExecutablePath para o local correto. Corrija também os valores das entradas (Padrão) e WindowedExecutablePath, conforme necessário.
   • Se o ambiente não existir mais no computador e você desejar removê-lo da janela Ambientes do Python, exclua o nó pai do número da versão do nó de InstallPath. A imagem anterior apresenta um exemplo desse nó. No exemplo, esse nó é 3.6.

   Cuidado

   Configurações inválidas na chave HKEY_CURRENT_USER\SOFTWARE\Python substituem as configurações na chave HKEY_LOCAL_MACHINE\SOFTWARE\Python.

Excluir ou remover um ambiente Python

Se quiser remover um projeto do Python, acesse o ambiente do Python no Gerenciador de Soluções. Clique com o botão direito do mouse no ambiente do Python que deseja remover e selecione Remover.

Caso queira manter o ambiente do Python e apenas removê-lo de um projeto, escolha Remover. Se preferir excluir o ambiente de forma permanente, escolha Excluir.

Conteúdo relacionado

• Instalar interpretadores do Python
• Selecionar um interpretador para um projeto
• Use requirements.txt para dependências
• Caminhos de pesquisa
• Referência da janela de ambientes do Python