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.