Instalando pacotes usando pip e ambientes virtuais

Este guia discute como instalar pacotes usando pip e um gerenciador de ambiente virtual: ou venv para Python 3 ou virtualenv para Python 2 Estas são as ferramentas de nível mais baixo para gerenciar pacotes Python e são recomendadas se as ferramentas de nível mais alto não atenderem às suas necessidades.

Nota

Este documento usa o termo pacote para se referir a um Pacote de Distribuição que é diferente de um Pacote de Importação que é usado para importar módulos em seu código-fonte do Python.

Instalando pip

pip é o gerenciador de pacotes de referência Python. É usado para instalar e atualizar pacotes. Você precisará certificar-se de que possui a versão mais recente do pip instalada.

O Debian e a maioria das outras distribuições incluem um pacote python-pip; se você deseja usar as versões fornecidas pela distribuição Linux do pip, consulte Instalando pip/setuptools/wheel com gerenciadores de pacotes do Linux.

Você também pode instalar o pip por conta própria para garantir que possui a versão mais recente. É recomendado usar o sistema pip para inicializar uma instalação de usuário do pip:

python3 -m pip install --user --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 21.1.3 from $HOME/.local/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 21.1.3 from c:\python39\lib\site-packages (Python 3.9.4)

Instalando virtualenv

Nota

Se você estiver usando o Python 3.3 ou mais recente, o módulo venv é a forma preferida de criar e gerenciar ambientes virtuais. venv está incluído na biblioteca padrão Python e não requer instalação adicional. Se você estiver usando venv, pode pular esta seção.

virtualenv é usado para gerenciar pacotes Python para diferentes projetos. O uso do virtualenv permite que você evite instalar pacotes Python globalmente, o que poderia quebrar as ferramentas do sistema ou outros projetos. Você pode instalar virtualenv usando pip.

python3 -m pip install --user virtualenv

py -m pip install --user virtualenv

Criando um ambiente virtual

venv (para Python 3) e virtualenv (para Python 2) permitem que você gerencie instalações de pacotes separadas para projetos diferentes. Eles essencialmente permitem que você crie uma instalação “virtual” isolada do Python e instale pacotes nessa instalação virtual. Ao trocar de projeto, você pode simplesmente criar um novo ambiente virtual e não precisa se preocupar em quebrar os pacotes instalados nos outros ambientes. É sempre recomendável usar um ambiente virtual ao desenvolver aplicações Python.

Para criar um ambiente virtual, vá até o diretório do seu projeto e execute venv. Se você estiver usando Python 2, substitua venv por virtualenv nos comandos abaixo.

python3 -m venv env

py -m venv env

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

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

Nota

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

Ativando um ambiente virtual

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

source env/bin/activate

.\env\Scripts\activate

Você pode confirmar que está no ambiente virtual verificando a localização do seu interpretador Python:

which python

where python

Deve estar no diretório env:

.../env/bin/python

...\env\Scripts\python.exe

Contanto que seu ambiente virtual esteja ativado, pip instalará pacotes naquele ambiente específico e você poderá importar e usar pacotes em sua aplicação Python.

Saindo do ambiente virtual

Se você deseja trocar de projeto ou de outra forma deixar seu ambiente virtual, basta executar:

deactivate

Se você deseja entrar novamente no ambiente virtual, basta seguir as mesmas instruções acima sobre como ativar um ambiente virtual. Não há necessidade de recriar o ambiente virtual.

Instalando pacotes

Agora que você está em seu ambiente virtual, pode instalar pacotes. 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

Instalando versões específicas

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

Instalando 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]"

Instalando a partir do código-fonte

pip pode instalar um pacote diretamente do código-fonte, por exemplo:

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 .

Instalando 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.

Instalando 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.

Usando outros índices de pacotes

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 arquivos 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

Isso é útil para criar Requirements Files que podem recriar as versões exatas de todos os pacotes instalados em um ambiente.