Instalando pacotes#

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

It’s important to note that the term “package” in this context is being used to describe a bundle of software to be installed (i.e. as a synonym for a distribution). It does not refer to the kind of package that you import in your Python source code (i.e. a container of modules). It is common in the Python community to refer to a distribution using the term “package”. Using the term “distribution” is often not preferred, because it can easily be confused with a Linux distribution, or another larger software distribution like Python itself.

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:

>>> python3 --version
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'python3' 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 is available by default in Python 3.3 and later, and installs pip into created virtual environments in Python 3.4 and later (Python versions prior to 3.12 also installed Setuptools).

  • 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).

In both of the above cases, Windows users should not use the source command, but should rather run the activate script directly from the command shell like so:

<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 . A descrição completa dos especificadores suportados podem ser encontrados na especificação de especificadores de versão. 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"

To install a version that’s compatible with a certain version: [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 SomeProject @ git+https://git.repo/some_pkg.git          # from git
python3 -m pip install -e SomeProject @ hg+https://hg.repo/some_pkg                # from mercurial
python3 -m pip install -e SomeProject @ svn+svn://svn.repo/some_pkg/trunk/         # from svn
python3 -m pip install -e SomeProject @ git+https://git.repo/some_pkg.git@feature  # from a branch

py -m pip install -e SomeProject @ git+https://git.repo/some_pkg.git          # from git
py -m pip install -e SomeProject @ hg+https://hg.repo/some_pkg                # from mercurial
py -m pip install -e SomeProject @ svn+svn://svn.repo/some_pkg/trunk/         # from svn
py -m pip install -e SomeProject @ git+https://git.repo/some_pkg.git@feature  # 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 compatível com a API de repositório simples, 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