Compartilhar via


Selecionar um ambiente Python para um projeto no Visual Studio

Todo o código em um projeto do Python é executado dentro do contexto de um ambiente específico. Esses ambientes podem ser um ambiente global do Python, um ambiente do Anaconda, um ambiente virtual ou um ambiente do Conda. O Visual Studio utiliza o ambiente do Python para depuração, importação, conclusão de membros e verificação de sintaxe. O ambiente é utilizado para todas as tarefas que exijam serviços de linguagem específicos da versão do Python e um conjunto de pacotes instalados.

No Visual Studio, é possível criar vários ambientes para um projeto e alternar entre eles conforme as suas necessidades específicas de desenvolvimento. Novos projetos do Python são inicialmente configurados para utilizar o ambiente global padrão. É possível conferir os ambientes de um projeto no nó Ambientes do Python no Gerenciador de Soluções:

Screenshot that shows the global default Python environment for a project in Solution Explorer in Visual Studio.

Pré-requisitos

Trocar o ambiente do projeto atual

No Visual Studio, é possível trocar o ambiente ativo (atual) de um projeto do Python pelo Gerenciador de Soluções ou pela barra de ferramentas utilizando a funcionalidade Adicionar Ambiente.

  1. Inicie o processo para Adicionar Ambiente:

    • No Gerenciador de Soluções, clique com o botão direito do mouse no nó Ambientes do Python referente ao seu projeto e escolha Adicionar Ambiente.
    • Como alternativa, na barra de ferramentas do Python, selecione Adicionar Ambiente no menu suspenso Ambiente.

    Screenshot that shows the two options to access the Add Environments feature in Visual Studio.

  2. Na caixa de diálogo Adicionar Ambiente, escolha a guia Ambiente existente. Expanda a lista suspensa Ambiente, selecione um ambiente e escolha Adicionar.

    Screenshot that shows how to select a project environment in the Add Environments dialog in Visual Studio.

Observação

Se o ambiente que você quiser utilizar não estiver listado, poderá ser necessário identificar manualmente um ambiente existente.

Usar ambientes virtuais

Um ambiente virtual é uma combinação exclusiva de um interpretador específico do Python e um conjunto específico de bibliotecas que é diferente de outros ambientes globais e do Conda. Um ambiente virtual é específico para um projeto e é mantido em uma subpasta do projeto. A pasta contém as bibliotecas instaladas do ambiente e um arquivo pyvenv.cfg que especifica o caminho do interpretador de base do ambiente no sistema de arquivos. (Um ambiente virtual não contém uma cópia do interpretador, apenas um link para ele.)

Um dos benefícios do uso de um ambiente virtual é que, à medida que você desenvolve um projeto, o ambiente virtual sempre reflete as dependências exatas do projeto. Esse comportamento é diferente de um ambiente global compartilhado, que contém qualquer quantidade de bibliotecas, independentemente de você utilizá-las ou não no projeto. Em um ambiente virtual, é possível criar facilmente um arquivo requirements.txt, que é usado para reinstalar as dependências do pacote em outros computadores de desenvolvimento ou produção. Para saber mais, confira Gerenciar pacotes necessários com requirements.txt.

Quando você abre um projeto no Visual Studio que contém um arquivo requirements.txt, o Visual Studio oferece automaticamente a opção de recriar o ambiente virtual. Em computadores em que o Visual Studio não está instalado, você pode usar o comando pip install -r requirements.txt para restaurar os pacotes necessários.

Como um ambiente virtual contém um caminho embutido em código para o interpretador de base do Python e é possível recriar o ambiente usando o arquivo requirements.txt, normalmente você omite a subpasta do ambiente no controle do código-fonte. Depois de adicionar um ambiente virtual ao projeto, ele será exibido na janela Ambientes do Python. Você pode ativá-lo como qualquer outro ambiente e gerenciar seus pacotes.

Criar um ambiente virtual

Você pode criar um novo ambiente virtual diretamente no Visual Studio da seguinte maneira:

  1. Inicie o processo para Adicionar Ambiente:

    • No Gerenciador de Soluções, clique com o botão direito do mouse no nó Ambientes do Python referente ao seu projeto e escolha Adicionar Ambiente.
    • Como alternativa, na barra de ferramentas do Python, selecione Adicionar Ambiente no menu suspenso Ambiente.
  2. Na caixa de diálogo Adicionar Ambiente, selecione a guia Ambiente virtual:

    Screenshot of the Virtual environment tab of the Add Environment dialog box in Visual Studio.

  3. Defina os campos obrigatórios:

    Campo obrigatório Descrição
    Projeto Identifique o projeto em que deseja criar um ambiente.
    Nome Informe um nome para o novo ambiente virtual.
    Interpretador de base Determine o interpretador da linguagem de base do ambiente virtual.
    Localidade O local padrão é atribuído ao ambiente virtual pelo sistema. Se quiser trocar o local, escolha o link Alterar local do ambiente virtual, acesse o local e selecione Selecionar pasta.
  4. Defina todos os campos opcionais desejados:

    Campo opcional Descrição
    Instalar pacotes usando o arquivo Determine o caminho para um arquivo requirements.txt a fim de adicionar pacotes ao ambiente virtual. Insira o local e o nome do arquivo ou acesse (...) o local dele e selecione-o.
    Definir como ambiente atual Depois que o ambiente for criado, ative o novo ambiente no projeto selecionado.
    Definir como ambiente padrão para novos projetos Defina e ative o ambiente automaticamente em todos os novos projetos criados no Visual Studio. Essa configuração também está disponível pela opção Tornar este o ambiente padrão para novos projetos na janela Ambientes do Python. Ao usar essa opção, coloque o ambiente virtual em um local fora de um projeto específico.
    Exibir na janela de ambientes do Python Especifique se deseja mostrar a janela Ambientes do Python depois de criar o ambiente.
    Tornar esse ambiente disponível globalmente Especifique se o ambiente virtual também deve atuar como um ambiente global. Ao usar essa opção, coloque o ambiente virtual em um local fora de um projeto específico.
  5. Selecione Criar para finalizar o ambiente virtual.

O Visual Studio exibe uma barra de progresso enquanto configura o ambiente, e baixa todos os pacotes necessários.

Depois que o processo for concluído, o Visual Studio ativará o novo ambiente virtual e o adicionará ao nó Ambientes do Python no Gerenciador de Soluções. O ambiente também pode ser encontrado na janela Ambientes do Python para o projeto contido.

Ativar um ambiente

Para ativar um ambiente existente em um projeto, realize as seguintes etapas:

  1. No Gerenciador de Soluções, expanda o nó Ambientes do Python do projeto e encontre o ambiente que deseja utilizar.

  2. Clique com o botão direito do mouse no ambiente e selecione Ativar Ambiente.

    Screenshot that shows how to activate a project environment in Visual Studio.

    Se o Visual Studio detectar um arquivo requirements.txt nesse ambiente, ele perguntará se deve instalar esses pacotes.

    Após a ativação do ambiente pelo Visual Studio, o nome do ambiente ativo aparece em negrito no Gerenciador de Soluções:

    Screenshot that shows how Visual Studio shows the name of the active environment in a bold font in Solution Explorer.

Remover um ambiente virtual

Para remover um ambiente existente em um projeto, realize as seguintes etapas:

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no ambiente virtual e escolha Remover.

  2. O Visual Studio pergunta se você quer remover ou excluir o ambiente virtual.

    • Selecione Remover para tornar o ambiente indisponível ao projeto, mas mantê-lo no sistema de arquivos.
    • Selecione Excluir para remover o ambiente do projeto e excluí-lo do sistema de arquivos. O interpretador de base não é afetado.

Visualizar e gerenciar os pacotes instalados

No Gerenciador de Soluções, é possível visualizar e gerenciar todos os pacotes instalados em um ambiente. Você pode importar esses pacotes e utilizá-los no código quando o ambiente estiver ativo.

  • Para visualizar rapidamente todos os pacotes instalados em um ambiente, expanda o nó do ambiente no nó Ambientes do Python do respectivo projeto no Gerenciador de Soluções:

    Screenshot that shows Python packages for an environment in Solution Explorer in Visual Studio.

  • Se quiser instalar novos pacotes ou gerenciar pacotes existentes, clique com o botão direito do mouse no nó do ambiente e escolha Gerenciar Pacotes do Python. Também é possível utilizar o botão de pacotes na barra de ferramentas do Python:

    Screenshot that shows how to access the Manage Python packages option for an environment in Solution Explorer.

    A janela Ambientes do Python é exibida, mostrando todos os pacotes instalados no ambiente selecionado na guia Pacotes (PyPI):

    Screenshot that shows the current packages for the selected environment in the Python Environments window.

    No Visual Studio, os pacotes e as dependências da maioria dos ambientes são baixados do Índice de Pacotes do Python (PyPI), onde você também pode pesquisar os pacotes disponíveis. A barra de status e a janela de saída do Visual Studio mostram informações sobre a instalação.

  • Se quiser desinstalar (remover) um pacote, encontre-o na lista e escolha o ícone de x à direita dele.

  • Para conferir se há versões atualizadas de um pacote ou pesquisar outros pacotes, insira um termo de pesquisa (em geral, um nome de pacote):

    O Visual Studio exibirá todos os pacotes correspondentes. Este exemplo mostra uma busca por pacotes com o termo blinker.

    Screenshot that shows how Visual Studio shows how to search for matching packages in the Python Environments window.

    O Visual Studio exibe uma lista de todos os resultados correspondentes na forma de links de comando ativos.

    • O primeiro comando atualiza o pacote para a versão e as dependências mais recentes. O comando é semelhante a Run command: pip install <package-name>. Se você pressionar Enter depois do termo da pesquisa, o Visual Studio executará automaticamente o primeiro comando.

    • Os outros links referem-se a comandos que instalam um pacote, uma versão ou uma dependência específica, como Install blinker-async (0.0.3). Escolha o respectivo link para executar um desses comandos.

Considerações sobre a instalação de pacotes

Ao trabalhar com pacotes no Visual Studio, lembre-se das seguintes considerações:

  • As entradas exibidas para os pacotes podem não ser precisas no que se refere à versão mais recente ou à disponibilidade. As informações de instalação e desinstalação exibidas para determinado pacote podem não ser confiáveis ou podem não estar disponíveis.

  • O Visual Studio usa o gerenciador de pacotes do PIP, se disponível, e o baixa e o instala quando necessário. O Visual Studio também pode usar o gerenciador de pacotes easy_install. Os pacotes instalados usando os comandos pip ou easy_install por meio da linha de comando também são exibidos.

  • Uma situação comum em que o PIP não conseguirá instalar um pacote ocorrerá quando o pacote incluir o código-fonte para componentes nativos em arquivos *.pyd. Sem a versão necessária do Visual Studio instalada, o PIP não pode compilar esses componentes. A mensagem de erro exibida nessa situação é erro: Não foi possível localizar vcvarsall.bat. O comando easy_install geralmente consegue baixar os binários pré-compilados, e você pode baixar um compilador adequado para versões mais antigas do Python em https://python.en.uptodown.com/windows/versions. Para obter mais informações, consulte Como lidar com o problema “Não é possível localizar vcvarsallbat” no blog da equipe das ferramentas do Python.

  • O gerenciador de pacotes conda geralmente usa https://repo.continuum.io/pkgs/ como padrão de canal, mas há outros canais disponíveis. Para obter mais informações, consulte Gerenciar Canais (docs.conda.io).

  • O Visual Studio ainda não oferece suporte ao uso do comando conda para instalar pacotes em um ambiente do Conda. Em vez disso, use o comando conda da linha de comando.