Instalando pacotes

Esta seção cobre o básico de como instalar pacotes Python.

É importante notar que o termo “pacote” neste contexto está sendo usado para descrever um pacote de software a ser instalado (ou seja, como um sinônimo para uma distribuição). Não se refere ao tipo de pacote que você importa em seu código-fonte Python (ou seja, um contêiner de módulos). É comum na comunidade Python referir-se a uma distribuição usando o termo “pacote”. Usar o termo “distribuição” geralmente não é preferido, porque pode ser facilmente confundido com uma distribuição Linux ou outra distribuição de software maior como o próprio Python.

Requisitos para instalar pacotes

Esta seção descreve as etapas a serem seguidas antes de instalar outros pacotes Python.

Certifique-se de que você consegue executar Python a partir da linha de comando

Antes de prosseguir, certifique-se de ter o Python e de que a versão esperada está disponível em sua linha de comando. Você pode verificar isso executando:

python3 --version
py --version

Você deve obter alguma saída como Python 3.6.3. Se você não tiver o Python, instale a versão 3.x mais recente de python.org ou consulte a seção Instalando Python do Guia do Mochileiro para Python.

Nota

Se você for um novato e receber um erro como este:

>>> python --version
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'python' is not defined

É porque este comando e outros comandos sugeridos neste tutorial devem ser executados em um shell (também chamado de terminal ou console). Veja o tutorial de introdução para iniciantes do Python para uma introdução sobre como usar o shell do seu sistema operacional e interagir com o Python.

Nota

Se estiver usando um shell aprimorado como o IPython ou o notebook Jupyter, você pode executar comandos do sistema como os deste tutorial precedendo-os com um caractere !:

In [1]: import sys
        !{sys.executable} --version
Python 3.6.3

É recomendado escrever {sys.executable} em vez de python simples para garantir que os comandos sejam executados na instalação do Python correspondendo ao ambiente em execução (que pode não ser o mesmo Python instalação à qual o comando python se refere).

Nota

Devido à forma como a maioria das distribuições Linux está lidando com a migração Python 3, os usuários Linux usando o sistema Python sem criar um ambiente virtual primeiro devem substituir o comando python neste tutorial por python3 e o comando python -m pip com python3 -m pip --user. Não execute nenhum dos comandos neste tutorial com sudo: se você receber um erro de permissão, volte para a seção sobre como criar ambientes virtuais, configure um e então continue com o tutorial como escrito.

Certifique-se de que você pode executar o pip a partir da linha de comando

Além disso, você precisa ter certeza de ter pip disponível. Você pode verificar isso executando:

python3 -m pip --version
py -m pip --version

Se você instalou Python a partir do código-fonte, com um instalador de python.org, ou via Homebrew, você já deve ter o pip. Se você estiver no Linux e instalado usando o gerenciador de pacotes do sistema operacional, pode ser necessário instalar o pip separadamente, consulte Instalando pip/setuptools/wheel com gerenciadores de pacotes do Linux.

Se o pip ainda não estiver instalado, tente primeiro inicializá-lo a partir da biblioteca padrão:

python3 -m ensurepip --default-pip
py -m ensurepip --default-pip

Se isso ainda não permitir que você execute python -m pip:

  • Baixe com segurança get-pip.py 1

  • Execute python get-pip.py. 2 Isso vai instalar ou atualizar o pip. Adicionalmente, vai instalar setuptools e wheel se ainda não estiverem instalados.

    Aviso

    Tenha cuidado se estiver usando uma instalação do Python gerenciada por seu sistema operacional ou outro gerenciador de pacotes. get-pip.py não coordena com essas ferramentas e pode deixar seu sistema em um estado inconsistente. Você pode usar python get-pip.py --prefix=/usr/local/ para instalar em /usr/local que é projetado para software instalado localmente.

Certifique-se que pip, setuptools e wheel estejam atualizados

Embora pip sozinho seja suficiente para instalar a partir de arquivos binários pré-compilados, cópias atualizadas dos projetos setuptools e wheel são úteis para garantir que você também possa instalar a partir de arquivos fonte:

python3 -m pip install --upgrade pip setuptools wheel
py -m pip install --upgrade pip setuptools wheel

Opcionalmente, crie um ambiente virtual

Veja a seção abaixo para detalhes, mas aqui está o comando básico de venv 3 para usar em um sistema Linux típico:

python3 -m venv tutorial_env
source tutorial_env/bin/activate
py -m venv tutorial_env
tutorial_env\Scripts\activate

Isso criará um novo ambiente virtual no subdiretório tutorial_env e configurará o shell atual para usá-lo como o ambiente python padrão.

Criando ambientes virtuais

“Ambientes virtuais” do Python permitem que pacotes Python sejam instalados em um local isolado para uma aplicação em particular, ao invés de serem instalados globalmente. Se você deseja instalar ferramentas de linha de comando globais com segurança, consulte Instalando ferramentas de linha de comando autônomas.

Imagine que você tenha uma aplicação que precisa da versão 1 do LibFoo, mas outra aplicação requer a versão 2. Como você pode usar essas duas aplicações? Se você instalar tudo em /usr/lib/python3.6/site-packages (ou qualquer que seja o local padrão de sua plataforma), é fácil acabar em uma situação em que você atualiza acidentalmente uma aplicação que não deveria ser atualizada.

Ou, de forma mais geral, e se você quiser instalar uma aplicação e deixá-la como está? Se uma aplicação funcionar, qualquer alteração em suas bibliotecas ou nas versões dessas bibliotecas pode interromper a aplicação.

Além disso, e se você não puder instalar pacotes no diretório global site-packages? Por exemplo, em um host compartilhado.

Em todos esses casos, os ambientes virtuais podem lhe ajudar. Eles têm seus próprios diretórios de instalação e não compartilham bibliotecas com outros ambientes virtuais.

Atualmente, existem duas ferramentas comuns para a criação de ambientes virtuais Python:

  • venv está disponível por padrão no Python 3.3 e posterior, e instala pip e setuptools em ambientes virtuais criados no Python 3.4 e posterior.

  • virtualenv precisa ser instalado separadamente, mas oferece suporte a Python 2.7+ e Python 3.3+, e pip, setuptools e wheel são sempre instalados em ambientes virtuais criados por padrão (independentemente da versão Python).

O uso básico é assim:

Usando venv:

python3 -m venv <DIR>
source <DIR>/bin/activate
py -m venv <DIR>
<DIR>\Scripts\activate

Usando virtualenv:

python3 -m virtualenv <DIR>
source <DIR>/bin/activate
virtualenv <DIR>
<DIR>\Scripts\activate

Para mais informações, veja a documentação do venv ou do virtualenv.

O uso de source em shells Unix garante que as variáveis do ambiente virtual sejam definidas dentro do shell atual, e não em um subprocesso (que então desaparece, sem nenhum efeito útil).

Em ambos os casos acima, os usuários Windows não devem _não_ usar o comando source, mas devem executar o script activate diretamente do shell de comando assim:

<DIR>\Scripts\activate

Gerenciar vários ambientes virtuais diretamente pode se tornar tedioso, então o tutorial de gerenciamento de dependências apresenta uma ferramenta de alto nível, Pipenv, que gerencia automaticamente um ambiente virtual separado para cada projeto e aplicação no qual você trabalha.

Usar pip para instalação

pip é o instalador recomendado. A seguir, cobriremos os cenários de uso mais comuns. Para obter mais detalhes, consulte a documentação do pip, que inclui um Guia de Referências completo.

Instalando a partir do PyPI

O uso mais comum do pip é instalar a partir do Python Package Index usando um especificador de requisitos. De modo geral, um especificador de requisitos é composto de um nome de projeto seguido por um especificador de versão opcional . PEP 440 contém uma especificação completa dos especificadores suportados atualmente. Abaixo estão alguns exemplos.

Para instalar a versão mais recente de “SomeProject”:

python3 -m pip install "SomeProject"
py -m pip install "SomeProject"

Para instalar uma versão específica:

python3 -m pip install "SomeProject==1.4"
py -m pip install "SomeProject==1.4"

Para instalar maior ou igual a uma versão e menor que outra:

python3 -m pip install "SomeProject>=1,<2"
py -m pip install "SomeProject>=1,<2"

Para instalar uma versão que é “compatível” com uma determinada versão: 4

python3 -m pip install "SomeProject~=1.4.2"
py -m pip install "SomeProject~=1.4.2"

Nesse caso, isso significa instalar qualquer versão “==1.4.*” que também seja “>=1.4.2”.

Distribuições de fonte vs Wheels

pip pode instalar a partir de Distribuições Fonte (sdist) ou Wheels, mas se ambos estiverem presentes no PyPI, pip irá preferir um wheel compatível. Você pode substituir o comportamento padrão do pip, por exemplo usando sua opção –no-binary.

Wheels são um formato de distribuição pré-construído que fornece uma instalação mais rápida em comparação com Distribuições Fonte (sdist), especialmente quando um projeto contém extensões compiladas.

Se pip não encontrar um wheel para instalar, ele irá construir um wheel localmente e armazená-lo em cache para instalações futuras, ao invés de reconstruir a distribuição fonte no futuro.

Atualizando pacotes

Atualize um SomeProject já instalado para o mais recente do PyPI.

python3 -m pip install --upgrade SomeProject
py -m pip install --upgrade SomeProject

Instalando para o site do usuário

Para instalar pacotes que são isolados para o usuário atual, use o sinalizador --user:

python3 -m pip install --user SomeProject
py -m pip install --user SomeProject

Para obter mais informações, consulte a seção User Installs da documentação do pip.

Observe que o sinalizador --user não tem efeito quando dentro de um ambiente virtual – todos os comandos de instalação afetarão o ambiente virtual.

Se SomeProject definir quaisquer scripts de linha de comando ou pontos de entrada de console, --user fará com que sejam instalados dentro do diretório binário da base do usuário, que pode ou não já estar presente em seu PATH do shell. (A partir da versão 10, pip exibe um aviso ao instalar qualquer script em um diretório fora de PATH.) Se os scripts não estiverem disponíveis em seu shell após a instalação, você precisará adicionar o diretório ao seu PATH:

  • No Linux e no macOS você pode encontrar o diretório binário da base do usuário executando python -m site --user-base e adicionando bin no final. Por exemplo, isso normalmente imprimirá ~/.local (com ~ expandido para o caminho absoluto para o seu diretório inicial), então você precisará adicionar ~/.local/bin para seu PATH. Você pode definir seu PATH permanentemente modificando ~/.profile.

  • No Windows você pode encontrar o diretório binário base do usuário executando py -m site --user-site e substituindo site-packages por Scripts. Por exemplo, isso poderia retornar C:\Users\Username\AppData\Roaming\Python36\site-packages, então você precisaria definir seu PATH para incluir C:\Users\Username\AppData\Roaming\Python36\Scripts. Você pode definir seu usuário PATH permanentemente no Painel de Controle. Você pode precisar encerrar a sessão para que as alterações de PATH tenham efeito.

Arquivos de requisitos

Instale uma lista de requisitos especificados em um arquivo de requisitos.

python3 -m pip install -r requirements.txt
py -m pip install -r requirements.txt

Instalando a partir de VCS

Instale um projeto a partir de VCS em um modo “editável”. Para um instrução completa da sintaxe, veja a seção do pip em VCS Support.

python3 -m pip install -e git+https://git.repo/some_pkg.git#egg=SomeProject          # from git
python3 -m pip install -e hg+https://hg.repo/some_pkg#egg=SomeProject                # from mercurial
python3 -m pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomeProject         # from svn
python3 -m pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomeProject  # from a branch
py -m pip install -e git+https://git.repo/some_pkg.git#egg=SomeProject          # from git
py -m pip install -e hg+https://hg.repo/some_pkg#egg=SomeProject                # from mercurial
py -m pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomeProject         # from svn
py -m pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomeProject  # from a branch

Instalando a partir de outros índices

Instalar a partir de um índice alternativo

python3 -m pip install --index-url http://my.package.repo/simple/ SomeProject
py -m pip install --index-url http://my.package.repo/simple/ SomeProject

Pesquise um índice adicional durante a instalação, além do PyPI

python3 -m pip install --extra-index-url http://my.package.repo/simple SomeProject
py -m pip install --extra-index-url http://my.package.repo/simple SomeProject

Instalando a partir de uma árvore de fontes local

Instale a partir dos fontes locais em Development Mode, ou seja, de tal forma que o projeto parece estar instalado, mas ainda seja editável a partir da árvore de fontes.

python3 -m pip install -e <path>
py -m pip install -e <path>

Você também pode instalar normalmente a partir dos fontes

python3 -m pip install <path>
py -m pip install <path>

Instalando de arquivos locais

Instale um arquivo de pacote fonte em particular.

python3 -m pip install ./downloads/SomeProject-1.0.4.tar.gz
py -m pip install ./downloads/SomeProject-1.0.4.tar.gz

Instale de um pacote contendo diretório local (e não verifique o PyPI)

python3 -m pip install --no-index --find-links=file:///local/dir/ SomeProject
python3 -m pip install --no-index --find-links=/local/dir/ SomeProject
python3 -m pip install --no-index --find-links=relative/dir/ SomeProject
py -m pip install --no-index --find-links=file:///local/dir/ SomeProject
py -m pip install --no-index --find-links=/local/dir/ SomeProject
py -m pip install --no-index --find-links=relative/dir/ SomeProject

Instalando a partir de outras fontes

Para instalar a partir de outras fontes de dados (por exemplo, armazenamento Amazon S3), você pode criar uma aplicação auxiliar que apresente os dados em um formato de índice compatível com PEP 503 e usar o sinalizador --extra-index-url para direcionar o pip para usar esse índice.

./s3helper --port=7777
python -m pip install --extra-index-url http://localhost:7777 SomeProject

Instalando pré-lançamentos

Encontre versões de pré-lançamento e desenvolvimento, além de versões estáveis. Por padrão, pip só encontra versões estáveis.

python3 -m pip install --pre SomeProject
py -m pip install --pre SomeProject

Instalando “Extras”

Extras são “variantes” opcionais de um pacote, que podem incluir dependências adicionais e, assim, habilitar funcionalidades adicionais do pacote. Se você deseja instalar um extra para um pacote que você sabe que publica um, você pode incluí-lo no comando de instalação pip:

python3 -m pip install SomePackage[PDF]
python3 -m pip install SomePackage[PDF]==3.0
python3 -m pip install -e .[PDF]  # editable project in current directory
py -m pip install SomePackage[PDF]
py -m pip install SomePackage[PDF]==3.0
py -m pip install -e .[PDF]  # editable project in current directory

1

“Segurança” neste contexto significa usar um navegador moderno ou uma ferramenta como curl que verifica os certificados SSL ao baixar de URLs https.

2

Dependendo da sua plataforma, isso pode exigir acesso de root ou de administrador. pip está atualmente considerando mudar isso tornando as instalações de usuário o comportamento padrão.

3

Começando com Python 3.4, venv (uma alternativa à biblioteca padrão para virtualenv) criará ambientes do virtualenv com pip pré-instalado, tornando-o uma alternativa igual a virtualenv.

4

O especificador de versão compatível foi aceito em PEP 440 e o suporte foi lançado em setuptools v8.0 e pip v6.0