Instalar pacotes em um ambiente virtual usando pip e venv#

Este guia discute como criar e ativar um ambiente virtual usando a ferramenta de ambiente virtual da biblioteca padrão venv e instalar pacotes. O guia aborda como:

  • Criar e ativar um ambiente virtual

  • Preparar o pip

  • Instalar pacotes em um ambinente virtual usando o comando pip

  • Usar e criar o arquivo de requisitos

Nota

Este guia se aplica a versões suportadas do Python, atualmente 3.8 e superior.

Nota

Este guia usa o termo pacote para se referir a um Pacote de Distribuição, o qual é comumente instalado a partir de um host externo. Ele é diferente do termo Pacote de Importação que se refere a importar módulos em seu código-fonte do Python.

Importante

Este guia tem como pré-requisito que você esteja usando uma versão oficial do Python obtida em <https://www.python.org/downloads/>. Se você estiver usando o gerenciador de pacotes do seu sistema operacional para instalar o Python, certifique-se de que o Python esteja instalado antes de prosseguir com estas etapas.

Criar e usar ambientes virtuais#

Criar um novo ambiente virtual#

venv (para Python 3) permite gerenciar instalações de pacotes separadas para projetos diferentes. Ele cria uma instalação Python “virtual” e isolada. Ao alternar projetos, você pode criar um novo ambiente virtual isolado de outros ambientes virtuais. Você se beneficia do ambiente virtual, pois os pacotes podem ser instalados com segurança e não interferirão no ambiente de outro projeto.

Dica

Recomenda-se usar um ambiente virtual ao trabalhar com pacotes de terceiros.

Para criar um ambiente virtual, acesse o diretório do seu projeto e execute o comando a seguir. Isso criará um novo ambiente virtual em uma pasta local chamada .venv:

python3 -m venv .venv

py -m venv .venv

O segundo argumento é o local para criar o ambiente virtual. Geralmente, você pode apenas criar isso em seu projeto e chamá-lo de .venv.

venv irá criar uma instalação virtual Python na pasta .venv.

Nota

Você deve excluir seu diretório de ambiente virtual de seu sistema de controle de versão usando .gitignore ou similar.

Ativar um ambiente virtual#

Antes de começar a instalar ou usar pacotes em seu ambiente virtual, você precisará ativá-lo, com activate. Ativar um ambiente virtual colocará os executáveis python e pip específicos do ambiente virtual no PATH de seu shell.

source .venv/bin/activate

.venv\Scripts\activate

Para confirmar o ambiente virtual está ativado, verifique o local do seu interpretador Python:

which python

where python

Enquanto o ambiente virtual estiver ativo, o comando acima irá gerar um caminho de arquivo que inclui o diretório .venv, terminando com o seguinte:

.venv/bin/python

.venv\Scripts\python

Enquanto um ambiente virtual estiver ativado, pip instalará pacotes naquele ambiente específico. Isso permite que você importe e use pacotes em sua aplicação Python.

Desativar um ambiente virtual#

Se você deseja trocar de projeto ou sair do seu ambiente virtual, desative o ambiente com deactivate:

deactivate

Nota

Fechar seu shell desativará o ambiente virtual. Se você abrir uma nova janela do shell e quiser usar o ambiente virtual, reative-o.

Reativar um ambiente virtual#

Se você quiser reativar um ambiente virtual existente, siga as mesmas instruções sobre como ativar um ambiente virtual. Não há necessidade de criar um novo ambiente virtual.

Preparar o pip#

pip é o gerenciador de pacotes de referência Python. É usado para instalar e atualizar pacotes. Ele é usado para instalar e atualizar pacotes em um ambiente virtual.

Os instaladores de Python para macOS incluem pip. No Linux, você pode ter que instalar um pacote adicional como python3-pip. Você pode ter certeza de que o pip está atualizado executando:

python3 -m pip install --upgrade pip
python3 -m pip --version

Depois disso, você deve ter a versão mais recente do pip instalado em seu site de usuário:

pip 23.3.1 from .../.venv/lib/python3.9/site-packages (python 3.9)

Os instaladores do Python para Windows incluem pip. Você pode garantir que o pip está atualizado usando:

py -m pip install --upgrade pip
py -m pip --version

Depois disso, você deve ter a versão mais recente do pip:

pip 23.3.1 from .venv\lib\site-packages (Python 3.9.4)

Instalar pacotes usando pip#

Quando seu ambiente virtual estiver ativado, você poderá instalar pacotes. Use o comando pip install para instalar pacotes.

Instalar um pacote#

Por exemplo, vamos instalar a biblioteca Requests do Python Package Index (PyPI):

python3 -m pip install requests

py -m pip install requests

pip deve baixar solicitações e todas as suas dependências e instalá-los:

Collecting requests
  Using cached requests-2.18.4-py2.py3-none-any.whl
Collecting chardet<3.1.0,>=3.0.2 (from requests)
  Using cached chardet-3.0.4-py2.py3-none-any.whl
Collecting urllib3<1.23,>=1.21.1 (from requests)
  Using cached urllib3-1.22-py2.py3-none-any.whl
Collecting certifi>=2017.4.17 (from requests)
  Using cached certifi-2017.7.27.1-py2.py3-none-any.whl
Collecting idna<2.7,>=2.5 (from requests)
  Using cached idna-2.6-py2.py3-none-any.whl
Installing collected packages: chardet, urllib3, certifi, idna, requests
Successfully installed certifi-2017.7.27.1 chardet-3.0.4 idna-2.6 requests-2.18.4 urllib3-1.22

Instalar uma versão específica do pacote#

pip permite que você especifique qual versão de um pacote instalar usando especificadores de versão. Por exemplo, para instalar uma versão específica do requests:

python3 -m pip install 'requests==2.18.4'

py -m pip install "requests==2.18.4"

Para instalar a versão 2.x mais recente do requests:

python3 -m pip install 'requests>=2.0.0,<3.0.0'

py -m pip install "requests>=2.0.0,<3.0.0"

Para instalar versões de pré-lançamento de pacotes, use o sinalizador --pre:

python3 -m pip install --pre requests

py -m pip install --pre requests

Instalar extras#

Alguns pacotes possuem extras opcionais. Você pode dizer ao pip para instalá-los especificando o extra entre colchetes:

python3 -m pip install 'requests[security]'

py -m pip install "requests[security]"

Instalar um pacote a partir do código-fonte#

pip pode instalar um pacote diretamente de seu código-fonteseu. Por exemplo, você pode instalar o código-fonte no diretório google-auth:

cd google-auth
python3 -m pip install .

cd google-auth
py -m pip install .

Além disso, pip pode instalar pacotes do código-fonte no modo de desenvolvimento, o que significa que as mudanças no diretório de código-fonte afetarão imediatamente o pacote instalado sem a necessidade de reinstalar:

python3 -m pip install --editable .

py -m pip install --editable .

Instalar a partir de sistemas de controle de versão#

pip pode instalar pacotes diretamente de seu sistema de controle de versão. Por exemplo, você pode instalar diretamente de um repositório git:

google-auth @ git+https://github.com/GoogleCloudPlatform/google-auth-library-python.git

Para mais informações sobre os sistemas de controle de versão suportados e sintaxe, consulte a documentação do pip em Suporte VCS.

Instalar a partir de arquivos locais#

Se você tiver uma cópia local de um arquivo do Pacote de Distribuição (um arquivo zip, wheel ou tar), você pode instalá-lo diretamente com pip:

python3 -m pip install requests-2.18.4.tar.gz

py -m pip install requests-2.18.4.tar.gz

Se você tiver um diretório contendo arquivos de vários pacotes, você pode dizer ao pip para procurar por pacotes lá e não usar o Python Package Index (PyPI) de forma alguma:

python3 -m pip install --no-index --find-links=/local/dir/ requests

py -m pip install --no-index --find-links=/local/dir/ requests

Isso é útil se você estiver instalando pacotes em um sistema com conectividade limitada ou se quiser controlar estritamente a origem dos pacotes de distribuição.

Instalar a partir de outros índices de pacote#

Se você quiser baixar pacotes de um índice diferente do Python Package Index (PyPI), você pode usar o sinalizador --index-url:

python3 -m pip install --index-url http://index.example.com/simple/ SomeProject

py -m pip install --index-url http://index.example.com/simple/ SomeProject

Se você deseja permitir pacotes do Python Package Index (PyPI) e de um índice separado, você pode usar a sinalização --extra-index-url em seu lugar:

python3 -m pip install --extra-index-url http://index.example.com/simple/ SomeProject

py -m pip install --extra-index-url http://index.example.com/simple/ SomeProject

Atualizando pacotes#

pip pode atualizar pacotes no local usando o sinalizador --upgrade. Por exemplo, para instalar a versão mais recente de requests e todas as suas dependências:

python3 -m pip install --upgrade requests

py -m pip install --upgrade requests

Usando um arquivo de requisitos#

Em vez de instalar pacotes individualmente, pip permite que você declare todas as dependências em um Arquivo de Requisitos. Por exemplo, você pode criar um arquivo requirements.txt contendo:

requests==2.18.4
google-auth==1.1.0

E diga ao pip para instalar todos os pacotes neste arquivo usando o sinalizador -r:

python3 -m pip install -r requirements.txt

py -m pip install -r requirements.txt

Congelando dependências#

Pip pode exportar uma lista de todos os pacotes instalados e suas versões usando o comando freeze:

python3 -m pip freeze

py -m pip freeze

O que resultará em uma lista de especificadores de pacote, como:

cachetools==2.0.1
certifi==2017.7.27.1
chardet==3.0.4
google-auth==1.1.1
idna==2.6
pyasn1==0.3.6
pyasn1-modules==0.1.4
requests==2.18.4
rsa==3.4.2
six==1.11.0
urllib3==1.22

O comando pip freeze útil para criar Requirements Files que podem recriar as versões exatas de todos os pacotes instalados em um ambiente.