# Instalando módulos Python (versão legada)

Autor:

  Greg Ward

Nota

Todo o pacote `distutils` foi descontinuado e será removido no Python 3.12. Esta documentação é mantida apenas como referência e será removida com o pacote. Veja a entrada no O que há de novo para mais informações.

Ver também

Instalando módulos Python

  A documentação de instalação do módulo atualizada. Para o uso regular do Python, você provavelmente deseja aquela documentação em vez desta.

Nota

Este documento está sendo mantido apenas até que a documentação do `setuptools` em https://setuptools.readthedocs.io/en/latest/setuptools.html cubra independentemente todas as informações relevantes atualmente incluídas aqui.

Nota

Este guia cobre apenas as ferramentas básicas para construir e distribuir extensões que são fornecidas como parte desta versão do Python. Ferramentas de terceiros oferecem alternativas mais fáceis de usar e mais seguras. Consulte a quick recommendations section no Guia do Usuário de Pacotes Python para maiores informações

## Introdução

No Python 2.0, a API `distutils` foi adicionada pela primeira vez à biblioteca padrão. Isso forneceu aos mantenedores das distros Linux uma maneira padrão de converter projetos Python em pacotes de distro Linux, e aos administradores de sistema uma maneira padrão de instalá-los diretamente nos sistemas de destino.

Nos muitos anos desde que o Python 2.0 foi lançado, acoplar fortemente o sistema de compilação e o instalador do pacote ao ciclo de lançamento do tempo de execução da linguagem tornou-se problemático e agora é recomendado que os projetos usem o instalador de pacotes `pip` e o sistema de compilação `setuptools`, ao invés de usar `distutils` diretamente.

Veja Instalando módulos Python e Distribuindo módulos Python para mais detalhes.

Esta documentação legada está sendo mantida apenas até que tenhamos certeza de que a documentação do `setuptools` cobre tudo o que é necessário.

### Distribuições de fonte baseadas em Distutils

Se você fizer o download de uma distribuição fonte do módulo, poderá saber rapidamente se ele foi empacotado e distribuído da maneira padrão, ou seja, usando o Distutils. Primeiro, o nome da distribuição e o número da versão aparecerão de forma proeminente no nome do arquivo baixado, por exemplo, `foo-1.0.tar.gz` ou `widget-0.9.7.zip`. Em seguida, o arquivo será descompactado em um diretório com nome semelhante: `foo-1.0` ou `widget-0.9.7`. Além disso, a distribuição conterá um script de configuração `setup.py`, e um arquivo chamado `README.txt` ou possivelmente apenas `README`, que deve explicar a construção e instalação da distribuição de módulo é uma simples questão de executar um comando de um terminal:

    python setup.py install

Para Windows, este comando deve ser executado de uma janela de prompt de comando (Iniciar ‣ Acessórios):

    setup.py install

Se tudo isso for verdade, então você já sabe como construir e instalar os módulos que acabou de baixar: execute o comando acima. A menos que você precise instalar coisas de uma maneira não padronizada ou personalizar o processo de construção, você realmente não precisa deste manual. Ou melhor, o comando acima é tudo que você precisa para extrair deste manual.

## Construção e instalação padrão

Conforme descrito na seção Distribuições de fonte baseadas em Distutils, construir e instalar uma distribuição de módulo usando o Distutils é geralmente um comando simples para executar a partir de um terminal:

    python setup.py install

### Variações de plataforma

Você deve sempre executar o comando de configuração a partir do diretório raiz da distribuição, ou seja, o subdiretório de nível superior no qual a distribuição fonte do módulo descompacta. Por exemplo, se você acabou de baixar uma distribuição fonte do módulo `foo-1.0.tar.gz` em um sistema Unix, a coisa normal a fazer é:

    gunzip -c foo-1.0.tar.gz | tar xf -    # unpacks into directory foo-1.0
    cd foo-1.0
    python setup.py install

No Windows, você provavelmente baixaria `foo-1.0.zip`. Se você baixou o arquivo para `C:\Temp`, então ele seria descompactado em `C:\Temp\foo-1.0`; você pode usar um manipulador de arquivo com uma interface gráfica de usuário (como WinZip) ou uma ferramenta de linha de comando (como unzip ou pkunzip) para descompactar o arquivo. Em seguida, abra uma janela de prompt de comando e execute:

    cd c:\Temp\foo-1.0
    python setup.py install

### Dividindo o trabalho

A execução de `setup.py install` constrói e instala todos os módulos de uma vez. Se você preferir trabalhar de forma incremental – especialmente útil se quiser personalizar o processo de construção ou se as coisas estiverem dando errado – você pode usar o script de configuração para fazer uma coisa por vez. Isto é particularmente útil quando a construção e instalação serão feitas por usuários diferentes – por exemplo, você pode querer construir uma distribuição de módulo e entregá-la a um administrador de sistema para instalação (ou faça você mesmo, com privilégios de superusuário).

Por exemplo, você pode construir tudo em uma etapa e, em seguida, instalar tudo em uma segunda etapa, invocando o script de configuração duas vezes:

    python setup.py build
    python setup.py install

Se você fizer isso, você notará que executar o comando install primeiro executa o comando build, que – neste caso – rapidamente nota que não tem nada a fazer, já que tudo no diretório `build` está atualizado.

Você pode não precisar dessa habilidade para quebrar as coisas com frequência se tudo o que fizer for instalar módulos baixados da rede, mas é muito útil para tarefas mais avançadas. Se você começar a distribuir seus próprios módulos e extensões Python, executará muitos comandos distutils individuais por conta própria.

### Como a construção funciona

Como implícito acima, o comando build é responsável por colocar os arquivos a serem instalados em um diretório de construção. Por padrão, é `build` na raiz da distribuição; se você está excessivamente preocupado com a velocidade, ou deseja manter a árvore de fontes intocada, você pode alterar o diretório de construção com a opção `--build-base`. Por exemplo:

    python setup.py build --build-base=/path/to/pybuild/foo-1.0

(Ou você poderia fazer isso permanentemente com uma diretiva em seu sistema ou arquivo de configuração pessoal do Distutils; consulte a seção Arquivos de configuração do Distutils.) Normalmente, isso não é necessário.

O layout padrão para a árvore de construção é o seguinte:

    --- build/ --- lib/
    or
    --- build/ --- lib.<plat>/
                   temp.<plat>/

onde `<plat>` expande-se para uma breve descrição do sistema operacional/plataforma de hardware atual e versão Python. A primeira forma, com apenas um diretório `lib`, é usada para “distribuições de módulos puros” – isto é, distribuições de módulos que incluem apenas módulos Python puros. Se uma distribuição de módulo contém quaisquer extensões (módulos escritos em C/C++), então a segunda forma, com dois diretórios `<plat>`, é usada. Nesse caso, o diretório `temp.plat` contém arquivos temporários gerados pelo processo de compilação/vinculação que não são realmente instalados. Em ambos os casos, o diretório `lib` (ou `lib.plat`) contém todos os módulos Python (Python puro e extensões) que serão instalados.

No futuro, mais diretórios serão adicionados para lidar com scripts Python, documentação, executáveis binários e tudo o mais que for necessário para lidar com o trabalho de instalação de módulos e aplicações Python.

### Como a instalação funciona

Depois que o comando build é executado (se você o executa explicitamente ou o comando install faz isso por você), o trabalho do comando install é relativamente simples: tudo o que ele tem a fazer é copiar tudo em `build/lib` (ou `build/lib.plat`) para o diretório de instalação escolhido.

Se você não escolher um diretório de instalação – ou seja, se você apenas executar `setup.py install`– então o comando install instala no local padrão para módulos Python de terceiros . Esse local varia de acordo com a plataforma e como você construiu/instalou o próprio Python. No Unix (e no macOS, que também é baseado no Unix), também depende se a distribuição de módulo que está sendo instalada é Python puro ou contém extensões (“não puras”):

Plataforma | Local de instalação padrão | Valor padrão | Notas
--- | --- | --- | ---
Unix (puro) | `prefix/lib/pythonX.Y/site-packages` | `/usr/local/lib/pythonX.Y/site-packages` | (1)
Unix (não puro) | `exec-prefix/lib/pythonX.Y/site-packages` | `/usr/local/lib/pythonX.Y/site-packages` | (1)
Windows | `prefix\Lib\site-packages` | `C:\PythonXY\Lib\site-packages` | (2)

Notas:

1. A maioria das distribuições Linux inclui Python como uma parte padrão do sistema, então `prefix` e `exec-prefix` são geralmente `/usr` no Linux. Se você construir Python no Linux (ou qualquer sistema semelhante ao Unix), o padrão de `prefix` e `exec-prefix` é `/usr/local`.

2. O diretório de instalação padrão no Windows era `C:\Program Files\Python` no Python 1.6a1, 1.5.2 e anterior.

`prefix` e `exec-prefix` representam os diretórios nos quais o Python é instalado e onde ele encontra suas bibliotecas em tempo de execução. Eles são sempre os mesmos no Windows, e muitas vezes os mesmos no Unix e macOS. Você pode descobrir o que sua instalação Python usa para `prefix` e `exec-prefix` executando Python no modo interativo e digitando alguns comandos simples. No Unix, apenas digite `python` no prompt do shell. No Windows, escolha Iniciar ‣ Programas ‣ Python X.Y ‣ Python (command line). Depois que o interpretador é iniciado, você digita o código Python no prompt. Por exemplo, em meu sistema Linux, eu digito as três instruções Python mostradas abaixo e obtenho a saída conforme mostrado, para descobrir meu `prefix` e `exec-prefix`:

    Python 2.4 (#26, Aug  7 2004, 17:19:02)
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import sys
    >>> sys.prefix
    '/usr'
    >>> sys.exec_prefix
    '/usr'

Alguns outros espaços reservados são usados neste documento: `X.Y` representa a versão do Python, por exemplo `3.2`; `abiflags` será substituído pelo valor de `sys.abiflags` ou pela string vazia para plataformas que não definem sinalizadores ABI; `distname` será substituído pelo nome da distribuição de módulo sendo instalado. Pontos e letras maiúsculas são importantes nos caminhos; por exemplo, um valor que usa `python3.2` no UNIX normalmente usará `Python32` no Windows.

Se você não deseja instalar módulos no local padrão, ou se não tem permissão para escrever lá, então você precisa ler sobre instalações alternativas na seção Instalação alternativa. Se você deseja personalizar seus diretórios de instalação mais intensamente, consulte a seção Instalação personalizada sobre instalações personalizadas.

## Instalação alternativa

Frequentemente, é necessário ou desejável instalar módulos em um local diferente do local padrão para módulos Python de terceiros. Por exemplo, em um sistema Unix, você pode não ter permissão para escrever no diretório de módulo de terceiros padrão. Ou você pode querer experimentar um módulo antes de torná-lo uma parte padrão da instalação local do Python. Isso é especialmente verdadeiro ao atualizar uma distribuição já presente: você deseja ter certeza de que sua base de scripts existente ainda funciona com a nova versão antes de realmente atualizar.

O comando install do Distutils é projetado para tornar a instalação de distribuições de módulos em um local alternativo simples e indolor. A ideia básica é que você forneça um diretório base para a instalação, e o comando install escolhe um conjunto de diretórios (chamado de esquema de instalação) neste diretório base no qual deseja instalar os arquivos. Os detalhes variam entre as plataformas, portanto, leia qualquer uma das seções a seguir que se aplique a você.

Observe que os vários esquemas de instalação alternativos são mutuamente exclusivos: você pode passar `--user`, ou `--home`, ou `--prefix` e `--exec-prefix`, ou `--install-base` e `--install-platbase`, mas você não pode misturar a partir destes grupos.

### Instalação alternativa: o esquema usuário

Este esquema foi projetado para ser a solução mais conveniente para usuários que não têm permissão de escrita no diretório global de pacotes de sites ou não desejam instalar nele. É habilitado com uma opção simples:

    python setup.py install --user

Os arquivos serão instalados em subdiretórios de `site.USER_BASE` (escrito como `userbase` daqui em diante). Este esquema instala módulos Python puros e módulos de extensão no mesmo local (também conhecido como `site.USER_SITE`). Aqui estão os valores para UNIX, incluindo macOS:

Tipo de arquivo | Diretório de instalação
--- | ---
módulos | `userbase/lib/pythonX.Y/site-packages`
scripts | `userbase/bin`
dados | `userbase`
cabeçalhos do C | `userbase/include/pythonX.Yabiflags/distname`

E aqui estão os valores usados no Windows:

Tipo de arquivo | Diretório de instalação
--- | ---
módulos | `userbase\PythonXY\site-packages`
scripts | `userbase\PythonXY\Scripts`
dados | `userbase`
cabeçalhos do C | `userbase\PythonXY\Include{distname}`

A vantagem de usar este esquema em comparação com os outros descritos abaixo é que o diretório de pacotes do site do usuário está, em condições normais, sempre incluído em `sys.path` (veja `site` para mais informações), o que significa que não há etapa adicional a ser executada após a execução do script `setup.py` para finalizar a instalação.

O comando build_ext também tem uma opção `--user` para adicionar `userbase/include` ao caminho de pesquisa do compilador para arquivos de cabeçalho e `userbase/lib` para o caminho de pesquisa do compilador para bibliotecas, bem como para o caminho de pesquisa em tempo de execução para bibliotecas C compartilhadas (rpath).

### Instalação alternativa: o esquema home

A ideia por trás do “esquema home” é que você construa e mantenha um estoque pessoal de módulos Python. O nome deste esquema é derivado da ideia de um diretório “home” no Unix, uma vez que não é incomum para um usuário Unix fazer seu diretório home ter um layout semelhante a `/usr/` ou `/usr/local/`. Este esquema pode ser usado por qualquer pessoa, independentemente do sistema operacional para o qual está instalando.

Instalando uma nova distribuição de módulo é tão simples quanto

    python setup.py install --home=<dir>

onde você pode fornecer qualquer diretório que desejar para a opção `--home`. No Unix, digitadores preguiçosos podem simplesmente digitar um til (`~`); o comando install vai expandir isso para o seu diretório home:

    python setup.py install --home=~

To make Python find the distributions installed with this scheme, you may have to modify Python’s search path or edit `sitecustomize` (see `site`) to call `site.addsitedir()` or edit `sys.path`.

A opção `--home` define o diretório base de instalação. Os arquivos são instalados nos seguintes diretórios na base de instalação da seguinte maneira:

Tipo de arquivo | Diretório de instalação
--- | ---
módulos | `home/lib/python`
scripts | `home/bin`
dados | `home`
cabeçalhos do C | `home/include/python/distname`

(Substitua mentalmente as barras por contrabarras se estiver no Windows.)

### Instalação alternativa: Unix (o esquema prefixo)

O “esquema prefixo” é útil quando você deseja usar uma instalação Python para realizar a compilação/instalação (ou seja, para executar o script de configuração), mas instalar módulos no diretório de módulo de terceiros de uma instalação Python diferente (ou algo que parece uma instalação diferente do Python). Se isso parece um pouco incomum, então é – é por isso que os esquemas usuário e home vêm antes. No entanto, existem pelo menos dois casos conhecidos em que o esquema prefixo será útil.

Primeiro, considere que muitas distribuições Linux colocam Python em `/usr`, ao invés do mais tradicional `/usr/local`. Isso é totalmente apropriado, já que, nesses casos, o Python é parte do “sistema” em vez de um complemento local. No entanto, se você estiver instalando módulos Python a partir do código-fonte, provavelmente deseja que eles entrem em `/usr/local/lib/python2.X` em vez de `/usr/lib/python2.X`. Isso pode ser feito com

    /usr/bin/python setup.py install --prefix=/usr/local

Outra possibilidade é um sistema de arquivos de rede onde o nome usado para escrever em um diretório remoto é diferente do nome usado para lê-lo: por exemplo, o interpretador Python acessado como `/usr/local/bin/python` pode pesquisar por módulos em `/usr/local/lib/python2.X`, mas esses módulos teriam que ser instalados em, digamos, `/mnt/@server/export/lib/python2.X`. Isso pode ser feito com

    /usr/local/bin/python setup.py install --prefix=/mnt/@server/export

Em ambos os casos, a opção `--prefix` define a base de instalação, e a opção `--exec-prefix` define a base de instalação específica da plataforma, que é usada para arquivos específicos da plataforma. (Atualmente, isso significa apenas distribuições de módulos não puros, mas pode ser expandido para bibliotecas C, executáveis binários, etc.) Se `--exec-prefix` não for fornecido, o padrão é `--prefix`. Os arquivos são instalados da seguinte forma:

Tipo de arquivo | Diretório de instalação
--- | ---
módulos Python | `prefix/lib/pythonX.Y/site-packages`
módulos de extensão | `exec-prefix/lib/pythonX.Y/site-packages`
scripts | `prefix/bin`
dados | `prefix`
cabeçalhos do C | `prefix/include/pythonX.Yabiflags/distname`

Não há nenhum requisito de que `--prefix` ou `--exec-prefix` realmente apontem para uma instalação alternativa do Python; se os diretórios listados acima ainda não existirem, eles serão criados no momento da instalação.

A propósito, a verdadeira razão pela qual o esquema prefixo é importante é simplesmente que uma instalação Unix padrão usa o esquema prefixo, mas com `--prefix` e `--exec-prefix` fornecidos pelo próprio Python como `sys.prefix` e `sys.exec_prefix`. Portanto, você pode pensar que nunca usará o esquema prefixo, mas toda vez que executa `python setup.py install` sem qualquer outra opção, você o está usando.

Observe que instalar extensões para uma instalação alternativa do Python não tem efeito sobre como essas extensões são construídas: em particular, os arquivos de cabeçalho Python (`Python.h` e amigos) instalados com o interpretador Python usado para executar o script de configuração vão ser usador na compilação de extensões. É sua responsabilidade garantir que o interpretador usado para executar as extensões instaladas dessa maneira seja compatível com o interpretador usado para criá-las. A melhor maneira de fazer isso é garantir que os dois interpretadores sejam da mesma versão do Python (possivelmente compilações diferentes ou possivelmente cópias da mesma compilação). (Claro, se seu `--prefix` e seu `--exec-prefix` nem mesmo apontam para uma instalação alternativa do Python, isso é imaterial.)

### Instalação alternativa: Windows (o esquema prefixo)

O Windows não tem o conceito de diretório pessoal do usuário e, como a instalação padrão do Python no Windows é mais simples do que no Unix, a opção `--prefix` tem sido tradicionalmente usada para instalar pacotes adicionais em locais separados no Windows.

    python setup.py install --prefix="\Temp\Python"

para instalar módulos para o diretório `\Temp\Python` na unidade atual.

A base de instalação é definida pela opção `--prefix`; a opção `--exec-prefix` não é suportada no Windows, o que significa que módulos Python puros e módulos de extensão são instalados no mesmo local. Os arquivos são instalados da seguinte forma:

Tipo de arquivo | Diretório de instalação
--- | ---
módulos | `prefix\Lib\site-packages`
scripts | `prefix\Scripts`
dados | `prefix`
cabeçalhos do C | `prefix\Include{distname}`

## Instalação personalizada

Às vezes, os esquemas de instalação alternativos descritos na seção Instalação alternativa simplesmente não fazem o que você quer. Você pode querer ajustar apenas um ou dois diretórios enquanto mantém tudo sob o mesmo diretório base, ou você pode querer redefinir completamente o esquema de instalação. Em ambos os casos, você está criando um esquema de instalação personalizada.

Para criar um esquema de instalação personalizada, você começa com um dos esquemas alternativos e substitui alguns dos diretórios de instalação usados para os vários tipos de arquivos, usando estas opções:

Tipo de arquivo | Opção de substituição
--- | ---
módulos Python | `--install-purelib`
módulos de extensão | `--install-platlib`
todos os módulos | `--install-lib`
scripts | `--install-scripts`
dados | `--install-data`
cabeçalhos do C | `--install-headers`

Essas opções de substituição podem ser relativas, absolutas ou explicitamente definidas em termos de um dos diretórios base da instalação. (Existem dois diretórios básicos de instalação, e eles são normalmente os mesmos – eles só diferem quando você usa o “esquema prefixo” do Unix e fornece opções diferentes de `--prefix` e `--exec-prefix`; usar `--install-lib` irá substituir os valores calculados ou fornecidos para `--install-purelib` e `--install-platlib`, e é recomendado para esquemas que não fazem diferença entre Python e módulos de extensão.)

Por exemplo, digamos que você esteja instalando uma distribuição de módulo em seu diretório pessoal no Unix – mas deseja que os scripts estejam em `~/scripts` em vez de `~/bin`. Como você pode esperar, você pode substituir este diretório com a opção `--install-scripts`; neste caso, faz mais sentido fornecer um caminho relativo, que será interpretado em relação ao diretório base da instalação (seu diretório home, neste caso):

    python setup.py install --home=~ --install-scripts=scripts

Outro exemplo Unix: suponha que sua instalação Python foi construída e instalada com um prefixo de `/usr/local/python`, então sob uma instalação padrão os scripts irão acabar em `/usr/local/python/bin`. Se você os quiser em `/usr/local/bin` em vez disso, você deve fornecer este diretório absoluto para a opção `--install-scripts`

    python setup.py install --install-scripts=/usr/local/bin

(Isso executa uma instalação usando o “esquema prefixo”, onde o prefixo é com o que seu interpretador Python foi instalado – `/usr/local/python` neste caso.)

Se você mantém o Python no Windows, pode querer que os módulos de terceiros fiquem em um subdiretório de `prefix`, ao invés do próprio `prefix`. Isso é quase tão fácil quanto personalizar o diretório de instalação do script – você apenas tem que lembrar que há dois tipos de módulos com os quais se preocupar, Python e módulos de extensão, que podem ser convenientemente controlados por uma opção:

    python setup.py install --install-lib=Site

O diretório de instalação especificado é relativo a `prefix`. Obviamente, você também deve garantir que esse diretório esteja no caminho de pesquisa do módulo do Python, por exemplo, colocando um arquivo `.pth` em um diretório de site (consulte `site`). Veja a seção Modificando o caminho de pesquisa do Python para descobrir como modificar o caminho de pesquisa do Python.

Se você deseja definir todo um esquema de instalação, basta fornecer todas as opções do diretório de instalação. A maneira recomendada de fazer isso é fornecer caminhos relativos; por exemplo, se você deseja manter todos os arquivos relacionados ao módulo Python em `python` em seu diretório home, e deseja um diretório separado para cada plataforma de onde você usa seu diretório inicial, você pode definir o seguinte esquema de instalação:

    python setup.py install --home=~ \
                            --install-purelib=python/lib \
                            --install-platlib=python/lib.$PLAT \
                            --install-scripts=python/scripts
                            --install-data=python/data

ou, equivalentemente,

    python setup.py install --home=~/python \
                            --install-purelib=lib \
                            --install-platlib='lib.$PLAT' \
                            --install-scripts=scripts
                            --install-data=data

`$PLAT` não é (necessariamente) uma variável de ambiente – ela será expandida pelo Distutils conforme ele analisa suas opções de linha de comando, assim como faz ao analisar seu(s) arquivo(s) de configuração.

Obviamente, especificar todo o esquema de instalação toda vez que você instalar uma nova distribuição de módulo seria muito tedioso. Assim, você pode colocar essas opções em seu arquivo de configuração Distutils (consulte a seção Arquivos de configuração do Distutils):

    [install]
    install-base=$HOME
    install-purelib=python/lib
    install-platlib=python/lib.$PLAT
    install-scripts=python/scripts
    install-data=python/data

ou, equivalentemente,

    [install]
    install-base=$HOME/python
    install-purelib=lib
    install-platlib=lib.$PLAT
    install-scripts=scripts
    install-data=data

Observe que esses dois não são equivalentes se você fornecer um diretório base de instalação diferente ao executar o script de configuração. Por exemplo,

    python setup.py install --install-base=/tmp

instalaria módulos puros em `/tmp/python/lib` no primeiro caso e em `/tmp/lib` no segundo caso. (Para o segundo caso, você provavelmente deseja fornecer uma base de instalação de `/tmp/python`.)

Você provavelmente notou o uso de `$HOME` e `$PLAT` na entrada do arquivo de configuração de amostra. Estas são variáveis de configuração Distutils, que apresentam uma forte semelhança com variáveis de ambiente. Na verdade, você pode usar variáveis de ambiente em arquivos de configuração em plataformas que têm essa noção, mas os Distutils definem adicionalmente algumas variáveis extras que podem não estar em seu ambiente, como `$PLAT`. (E, claro, em sistemas que não têm variáveis de ambiente, como Mac OS 9, as variáveis de configuração fornecidas pelo Distutils são as únicas que você pode usar.) Consulte a seção Arquivos de configuração do Distutils para detalhes.

Nota

Quando um ambiente virtual é ativado, quaisquer opções que alterem o caminho de instalação serão ignoradas de todos os arquivos de configuração distutils para evitar a instalação inadvertida de projetos fora do ambiente virtual.

### Modificando o caminho de pesquisa do Python

Quando o interpretador Python executa uma instrução `import`, ele procura tanto o código Python quanto os módulos de extensão ao longo de um caminho de busca. Um valor padrão para o caminho é configurado no binário Python quando o interpretador é construído. Você pode determinar o caminho importando o módulo `sys` e imprimindo o valor de `sys.path`.

    $ python
    Python 2.2 (#11, Oct  3 2002, 13:31:27)
    [GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import sys
    >>> sys.path
    ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
     '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
     '/usr/local/lib/python2.3/site-packages']
    >>>

A string nula em `sys.path` representa o diretório de trabalho atual.

A convenção esperada para pacotes instalados localmente é colocá-los no diretório `.../site-packages/`, mas você pode querer instalar módulos Python em algum diretório arbitrário. Por exemplo, seu site pode ter uma convenção de manter todos os softwares relacionados ao servidor da web em `/www`. Módulos add-on Python podem então pertencer a `/www/python`, e para importá-los, este diretório deve ser adicionado a `sys.path`. Existem várias maneiras de adicionar o diretório.

A maneira mais conveniente é adicionar um arquivo de configuração de caminho a um diretório que já está no caminho do Python, geralmente para o diretório `.../site-packages/`. Os arquivos de configuração de caminho têm uma extensão de `.pth`, e cada linha deve conter um único caminho que será anexado a `sys.path`. (Como os novos caminhos são anexados a `sys.path`, os módulos nos diretórios adicionados não substituirão os módulos padrão. Isso significa que você não pode usar este mecanismo para instalar versões fixas de módulos padrão.)

Os caminhos podem ser absolutos ou relativos, nesse caso eles são relativos ao diretório que contém o arquivo `.pth`. Veja a documentação do módulo `site` para mais informações.

Uma maneira um pouco menos conveniente é editar o arquivo `site.py` na biblioteca padrão do Python e modificar `sys.path`. `site.py` é importado automaticamente quando o interpretador Python é executado, a menos que a opção `-S` seja fornecida para suprimir este comportamento. Portanto, você pode simplesmente editar `site.py` e adicionar duas linhas a ele:

    import sys
    sys.path.append('/www/python/')

However, if you reinstall the same minor version of Python (perhaps when upgrading from 2.2 to 2.2.2, for example) `site.py` will be overwritten by the stock version. You’d have to remember that it was modified and save a copy before doing the installation.

Existem duas variáveis de ambiente que podem modificar `sys.path`. `PYTHONHOME` define um valor alternativo para o prefixo da instalação do Python. Por exemplo, se `PYTHONHOME` estiver definida como `/www/python`, o caminho de pesquisa será definido como `['', '/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2', ...]`.

A variável `PYTHONPATH` pode ser definida como uma lista de caminhos que serão adicionados ao início de `sys.path`. Por exemplo, se `PYTHONPATH` estiver definida como `/www/python:/opt/py`, o caminho de pesquisa começará com `['/www/python', '/opt/py']`. (Observe que os diretórios devem existir para serem adicionados ao `sys.path`; o módulo `site` remove caminhos que não existem.)

Finalmente, `sys.path` é apenas uma lista Python regular, então qualquer aplicação Python pode modificá-la adicionando ou removendo entradas.

## Arquivos de configuração do Distutils

Conforme mencionado acima, você pode usar os arquivos de configuração do Distutils para registrar preferências pessoais ou do site para qualquer opção do Distutils. Ou seja, qualquer opção para qualquer comando pode ser armazenada em um de dois ou três (dependendo da sua plataforma) arquivos de configuração, que serão consultados antes que a linha de comando seja analisada. Isso significa que os arquivos de configuração sobrescreverão os valores padrão e a linha de comando, por sua vez, sobrescreverá os arquivos de configuração. Além disso, se vários arquivos de configuração se aplicarem, os valores dos arquivos “anteriores” serão substituídos pelos arquivos “posteriores”.

### Localização e nomes dos arquivos de configuração

The names and locations of the configuration files vary slightly across platforms. On Unix and macOS, the three configuration files (in the order they are processed) are:

Tipo de arquivo | Localização e nome de arquivo | Notas
--- | --- | ---
sistema | `prefix/lib/pythonver/distutils/distutils.cfg` | (1)
pessoal | `$HOME/.pydistutils.cfg` | (2)
local | `setup.cfg` | (3)

E no Windows, os arquivos de configuração são:

Tipo de arquivo | Localização e nome de arquivo | Notas
--- | --- | ---
sistema | `prefix\Lib\distutils\distutils.cfg` | (4)
pessoal | `%HOME%\pydistutils.cfg` | (5)
local | `setup.cfg` | (3)

On all platforms, the “personal” file can be temporarily disabled by passing the `--no-user-cfg` option.

Notas:

1. Estritamente falando, o arquivo de configuração de todo o sistema reside no diretório onde os Distutils estão instalados; no Python 1.6 e posterior no Unix, isso é mostrado. Para Python 1.5.2, o Distutils normalmente será instalado em `prefix/lib/python1.5/site-packages/distutils`, então o arquivo de configuração do sistema deve ser colocado lá em Python 1.5.2.

2. On Unix, if the `HOME` environment variable is not defined, the user’s home directory will be determined with the `getpwuid()` function from the standard `pwd` module. This is done by the `os.path.expanduser()` function used by Distutils.

3. Ou seja, no diretório atual (geralmente a localização do script de configuração).

4. (Consulte também a nota (1).) No Python 1.6 e posterior, o “prefixo de instalação” padrão do Python é `C:\Python`, então o arquivo de configuração do sistema é normalmente `C:\Python\Lib\distutils\distutils.cfg`. No Python 1.5.2, o prefixo padrão era `C:\Arquivos de programas\Python`, e os Distutils não faziam parte da biblioteca padrão – de forma que o arquivo de configuração do sistema seria `C:\Arquivos de programas\Python\distutils\distutils.cfg` em uma instalação padrão do Python 1.5.2 no Windows.

5. No Windows, Se a variável de ambiente `HOME` não estiver definida, `USERPROFILE`, então `HOMEDRIVE` e, por fim, `HOMEPATH` serão tentados. Isso é feito pela função `os.path.expanduser()` usada pelo Distutils.

### Sintaxe dos arquivos de configuração

The Distutils configuration files all have the same syntax. The config files are grouped into sections. There is one section for each Distutils command, plus a `global` section for global options that affect every command. Each section consists of one option per line, specified as `option=value`.

For example, the following is a complete config file that just forces all commands to run quietly by default:

    [global]
    verbose=0

If this is installed as the system config file, it will affect all processing of any Python module distribution by any user on the current system. If it is installed as your personal config file (on systems that support them), it will affect only module distributions processed by you. And if it is used as the `setup.cfg` for a particular module distribution, it affects only that distribution.

You could override the default “build base” directory and make the build* commands always forcibly rebuild all files with the following:

    [build]
    build-base=blib
    force=1

which corresponds to the command-line arguments

    python setup.py build --build-base=blib --force

except that including the build command on the command-line means that command will be run. Including a particular command in config files has no such implication; it only means that if the command is run, the options in the config file will apply. (Or if other commands that derive values from it are run, they will use the values in the config file.)

You can find out the complete list of options for any command using the `--help` option, e.g.:

    python setup.py build --help

and you can find out the complete list of global options by using `--help` without a command:

    python setup.py --help

See also the “Reference” section of the “Distributing Python Modules” manual.

## Building Extensions: Tips and Tricks

Whenever possible, the Distutils try to use the configuration information made available by the Python interpreter used to run the `setup.py` script. For example, the same compiler and linker flags used to compile Python will also be used for compiling extensions. Usually this will work well, but in complicated situations this might be inappropriate. This section discusses how to override the usual Distutils behaviour.

### Tweaking compiler/linker flags

Compiling a Python extension written in C or C++ will sometimes require specifying custom flags for the compiler and linker in order to use a particular library or produce a special kind of object code. This is especially true if the extension hasn’t been tested on your platform, or if you’re trying to cross-compile Python.

In the most general case, the extension author might have foreseen that compiling the extensions would be complicated, and provided a `Setup` file for you to edit. This will likely only be done if the module distribution contains many separate extension modules, or if they often require elaborate sets of compiler flags in order to work.

A `Setup` file, if present, is parsed in order to get a list of extensions to build. Each line in a `Setup` describes a single module. Lines have the following structure:

    module ... [sourcefile ...] [cpparg ...] [library ...]

Let’s examine each of the fields in turn.

- module is the name of the extension module to be built, and should be a valid Python identifier. You can’t just change this in order to rename a module (edits to the source code would also be needed), so this should be left alone.

- sourcefile is anything that’s likely to be a source code file, at least judging by the filename. Filenames ending in `.c` are assumed to be written in C, filenames ending in `.C`, `.cc`, and `.c++` are assumed to be C++, and filenames ending in `.m` or `.mm` are assumed to be in Objective C.

- cpparg is an argument for the C preprocessor, and is anything starting with `-I`, `-D`, `-U` or `-C`.

- library is anything ending in `.a` or beginning with `-l` or `-L`.

If a particular platform requires a special library on your platform, you can add it by editing the `Setup` file and running `python setup.py build`. For example, if the module defined by the line

    foo foomodule.c

must be linked with the math library `libm.a` on your platform, simply add `-lm` to the line:

    foo foomodule.c -lm

Arbitrary switches intended for the compiler or the linker can be supplied with the `-Xcompiler` arg and `-Xlinker` arg options:

    foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm

The next option after `-Xcompiler` and `-Xlinker` will be appended to the proper command line, so in the above example the compiler will be passed the `-o32` option, and the linker will be passed `-shared`. If a compiler option requires an argument, you’ll have to supply multiple `-Xcompiler` options; for example, to pass `-x c++` the `Setup` file would have to contain `-Xcompiler -x -Xcompiler c++`.

Compiler flags can also be supplied through setting the `CFLAGS` environment variable. If set, the contents of `CFLAGS` will be added to the compiler flags specified in the `Setup` file.

### Using non-Microsoft compilers on Windows

#### Borland/CodeGear C++

This subsection describes the necessary steps to use Distutils with the Borland C++ compiler version 5.5. First you have to know that Borland’s object file format (OMF) is different from the format used by the Python version you can download from the Python or ActiveState web site. (Python is built with Microsoft Visual C++, which uses COFF as the object file format.) For this reason you have to convert Python’s library `python25.lib` into the Borland format. You can do this as follows:

    coff2omf python25.lib python25_bcpp.lib

The `coff2omf` program comes with the Borland compiler. The file `python25.lib` is in the `Libs` directory of your Python installation. If your extension uses other libraries (zlib, …) you have to convert them too.

The converted files have to reside in the same directories as the normal libraries.

How does Distutils manage to use these libraries with their changed names? If the extension needs a library (eg. `foo`) Distutils checks first if it finds a library with suffix `_bcpp` (eg. `foo_bcpp.lib`) and then uses this library. In the case it doesn’t find such a special library it uses the default name (`foo.lib`.) [1]

To let Distutils compile your extension with Borland C++ you now have to type:

    python setup.py build --compiler=bcpp

If you want to use the Borland C++ compiler as the default, you could specify this in your personal or system-wide configuration file for Distutils (see section Arquivos de configuração do Distutils.)

Ver também

C++Builder Compiler

  Information about the free C++ compiler from Borland, including links to the download pages.

Creating Python Extensions Using Borland’s Free Compiler

  Document describing how to use Borland’s free command-line C++ compiler to build Python.

#### GNU C / Cygwin / MinGW

This section describes the necessary steps to use Distutils with the GNU C/C++ compilers in their Cygwin and MinGW distributions. [2] For a Python interpreter that was built with Cygwin, everything should work without any of these following steps.

Not all extensions can be built with MinGW or Cygwin, but many can. Extensions most likely to not work are those that use C++ or depend on Microsoft Visual C extensions.

To let Distutils compile your extension with Cygwin you have to type:

    python setup.py build --compiler=cygwin

and for Cygwin in no-cygwin mode [3] or for MinGW type:

    python setup.py build --compiler=mingw32

If you want to use any of these options/compilers as default, you should consider writing it in your personal or system-wide configuration file for Distutils (see section Arquivos de configuração do Distutils.)

##### Older Versions of Python and MinGW

The following instructions only apply if you’re using a version of Python inferior to 2.4.1 with a MinGW inferior to 3.0.0 (with binutils-2.13.90-20030111-1).

These compilers require some special libraries. This task is more complex than for Borland’s C++, because there is no program to convert the library. First you have to create a list of symbols which the Python DLL exports. (You can find a good program for this task at https://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/).

    pexports python25.dll >python25.def

The location of an installed `python25.dll` will depend on the installation options and the version and language of Windows. In a “just for me” installation, it will appear in the root of the installation directory. In a shared installation, it will be located in the system directory.

Then you can create from these information an import library for gcc.

    /cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a

The resulting library has to be placed in the same directory as `python25.lib`. (Should be the `libs` directory under your Python installation directory.)

If your extension uses other libraries (zlib,…) you might have to convert them too. The converted files have to reside in the same directories as the normal libraries do.

Ver também

Building Python modules on MS Windows platform with MinGW

  Information about building the required libraries for the MinGW environment.

Notas de rodapé

[1]

This also means you could replace all existing COFF-libraries with OMF-libraries of the same name.

[2]

Check https://www.sourceware.org/cygwin/ for more information

[3]

Then you have no POSIX emulation available, but you also don’t need `cygwin1.dll`.