# 1. Linha de comando e ambiente

O interpretador do CPython verifica a linha de comando e o ambiente em busca de várias configurações.

CPython implementation detail: Os esquemas de linha de comando de outras implementações podem ser diferentes. Consulte Implementações Alternativas para mais recursos.

## 1.1. Linha de comando

Ao invocar o Python, você pode especificar qualquer uma destas opções:

    python [-bBdEhiIOqsSuvVWx?] [-c command | -m module-name | script | - ] [args]

O caso de uso mais comum é, obviamente, uma simples invocação de um script:

    python myscript.py

### 1.1.1. Opções de interface

A interface do interpretador é semelhante à do console do UNIX, mas fornece alguns métodos adicionais de chamada:

- Quando chamado com a entrada padrão conectada a um dispositivo tty, ele solicita comandos e os executa até um EOF (um caractere de fim de arquivo, você pode produzi-lo com `Ctrl-D` no UNIX ou `Ctrl-Z, Enter` no Windows) ser lido.

- Quando chamado com um argumento de nome de arquivo ou com um arquivo como entrada padrão, ele lê e executa um script desse arquivo.

- Quando chamado com um argumento de nome de diretório, ele lê e executa um script nomeado adequadamente desse diretório.

- Quando chamado com `-c command`, ele executa as instruções Python fornecidas como command. Aqui command pode conter várias instruções separadas por novas linhas. O espaço em branco à esquerda é significativo nas instruções do Python!

- Quando chamado com `-m module-name`, o módulo fornecido está localizado no caminho do módulo Python e é executado como um script.

No modo não interativo, toda a entrada é analisada antes de ser executada.

Uma opção de interface termina a lista de opções consumidas pelo interpretador, todos os argumentos consecutivos terminam em `sys.argv` – observe que o primeiro elemento, subscrito zero (`sys.argv[0]`) , é uma string que reflete a fonte do programa.

`-c``<command>`

  Executa o código Python em command. command pode ser uma ou mais instruções separadas por novas linhas, com espaços em branco à esquerda significativos, como no código normal do módulo.

  Se esta opção for fornecida, o primeiro elemento de `sys.argv` será `"-c"` e o diretório atual será adicionado ao início de `sys.path` (permitindo módulos nesse diretório para ser importado como módulos de nível superior).

`-m``<module-name>`

  Procura `sys.path` pelo módulo nomeado e executa seu conteúdo como o módulo `__main__`.

  Como o argumento é um nome de module, você não deve fornecer uma extensão de arquivo (`.py`). O nome do módulo deve ser um nome de módulo Python absoluto válido, mas a implementação nem sempre pode impor isso (por exemplo, pode permitir que você use um nome que inclua um hífen).

  Nomes de pacotes (incluindo pacotes de espaço de nomes) também são permitidos. Quando um nome de pacote é fornecido ao invés de um módulo normal, o interpretador irá executar `<pkg>.__main__` como o módulo principal. Esse comportamento é deliberadamente semelhante ao tratamento de diretórios e arquivos zip que são passados para o interpretador como o argumento do script.

  Nota

  Esta opção não pode ser usada com módulos embutidos e módulos de extensão escritos em C, uma vez que eles não possuem arquivos de módulo Python. No entanto, ele ainda pode ser usado para módulos pré-compilados, mesmo se o arquivo fonte original não estiver disponível.

  Se esta opção for fornecida, o primeiro elemento de `sys.argv` será o caminho completo para o arquivo do módulo (enquanto o arquivo do módulo está sendo localizado, o primeiro elemento será definido como `"-m"`). Como com a opção `-c`, o diretório atual será adicionado ao início de `sys.path`.

  Muitos módulos de biblioteca padrão contêm código que é chamado em sua execução como um script. Um exemplo é o módulo `timeit`:

      python -mtimeit -s 'setup here' 'benchmarked code here'
      python -mtimeit -h # for details

  Ver também

  `runpy.run_module()`

    Funcionalidade equivalente diretamente disponível para o código Python

  PEP 338 – Executando módulos como scripts

  Alterado na versão 3.1: Forneça o nome do pacote para executar um submódulo `__main__`.

  Alterado na versão 3.4: pacotes de espaço de nomes também são suportados

`-`

  Lê os comandos da entrada padrão (`sys.stdin`). Se a entrada padrão for um terminal, `-i` está implícito.

  Se esta opção for fornecida, o primeiro elemento de `sys.argv` será `"-"` e o diretório atual será adicionado ao início de `sys.path`.

`<script>`

  Executa o código Python contido em script, que deve ser um caminho do sistema de arquivos (absoluto ou relativo) referindo-se a um arquivo Python, um diretório contendo um arquivo `__main__.py`, ou um arquivo zip contendo um arquivo `__main__.py`.

  Se esta opção for fornecida, o primeiro elemento de `sys.argv` será o nome do script conforme fornecido na linha de comando.

  Se o nome do script se referir diretamente a um arquivo Python, o diretório que contém esse arquivo é adicionado ao início de `sys.path`, e o arquivo é executado como o módulo `__main__`.

  Se o nome do script se referir a um diretório ou arquivo zip, o nome do script será adicionado ao início de `sys.path` e o arquivo `__main__.py` nesse local será executado como o módulo `__main__`.

  Ver também

  `runpy.run_path()`

    Funcionalidade equivalente diretamente disponível para o código Python

Se nenhuma opção de interface for fornecida, `-i` está implícito, `sys.argv[0]` é uma string vazia (`""`) e o diretório atual será adicionado ao início de `sys.path`. Além disso, o preenchimento por tab e a edição do histórico são habilitados automaticamente, se disponíveis em sua plataforma (veja Configuração Readline).

Ver também

Chamando o interpretador

Alterado na versão 3.4: Ativação automática de preenchimento com tab e edição de histórico.

### 1.1.2. Opções genéricas

`-?```
`-h```
`--help```

  Imprime uma breve descrição de todas as opções de linha de comando.

`-V```
`--version```

  Imprime o número da versão do Python e saia. O exemplo de saída poderia ser:

      Python 3.6.0b2+

  Quando fornecido duas vezes, imprime mais informações sobre a construção, como:

      Python 3.6.0b2+ (3.6:84a3c5003510+, Oct 26 2016, 02:33:55)
      [GCC 6.2.0 20161005]

  Novo na versão 3.6: A opção `-VV`.

### 1.1.3. Opções diversas

`-b```

  Emite um aviso ao comparar `bytes` ou `bytearray` com `str` ou `bytes` com `int`. Emite um erro quando a opção é fornecida duas vezes (`-bb`).

  Alterado na versão 3.5: Afeta comparações de `bytes` com `int`.

`-B```

  Se fornecido, Python não tentará escrever arquivos `.pyc` na importação de módulos fonte. Veja também `PYTHONDONTWRITEBYTECODE`.

`-d```

  Turn on parser debugging output (for wizards only, depending on compilation options). See also `PYTHONDEBUG`.

`-E```

  Ignora todas as variáveis de ambiente `PYTHON*`, por exemplo `PYTHONPATH` e `PYTHONHOME`, que pode ser definido.

`-i```

  Quando um script é passado como primeiro argumento ou a opção `-c` é usada, entre no modo interativo depois de executar o script ou o comando, mesmo quando `sys.stdin` não parece ser um terminal. O arquivo `PYTHONSTARTUP` não foi lido.

  Isso pode ser útil para inspecionar variáveis globais ou um stack trace (situação da pilha de execução) quando um script levanta uma exceção. Veja também `PYTHONINSPECT`.

`-I```

  Executa o Python no modo isolado. Isso também implica -E e -s. No modo isolado `sys.path` não contém o diretório do script nem o diretório de pacotes do site do usuário. Todas as variáveis de ambiente `PYTHON*` são ignoradas também. Outras restrições podem ser impostas para evitar que o usuário injete código malicioso.

  Novo na versão 3.4.

`-O```

  Remova as instruções de asserção e qualquer código condicional ao valor de `__debug__`. Aumenta o nome do arquivo para arquivos compilados (bytecode) adicionando `.opt-1` antes da extensão `.pyc` (veja PEP 488). Veja também `PYTHONOPTIMIZE`.

  Alterado na versão 3.5: Modifica nomes de arquivos `.pyc` conforme a PEP 488.

`-OO```

  Faz o mesmo que `-O` e também descarta docstrings. Aumenta o nome do arquivo para arquivos compilados (bytecode) adicionando `.opt-2` antes da extensão `.pyc` (veja PEP 488).

  Alterado na versão 3.5: Modifica nomes de arquivos `.pyc` conforme a PEP 488.

`-q```

  Não exibe as mensagens de copyright e de versão nem mesmo no modo interativo.

  Novo na versão 3.2.

`-R```

  Kept for compatibility. On Python 3.3 and greater, hash randomization is turned on by default.

  On previous versions of Python, this option turns on hash randomization, so that the `__hash__()` values of str, bytes and datetime are “salted” with an unpredictable random value. Although they remain constant within an individual Python process, they are not predictable between repeated invocations of Python.

  A aleatorização com hash se destina a fornecer proteção contra uma negação de serviço causada por entradas cuidadosamente escolhidas que exploram o pior caso de desempenho de uma inserção de dicionário, complexidade O(n^2). Consulte http://www.ocert.org/advisories/ocert-2011-003.html para obter detalhes.

  `PYTHONHASHSEED` permite que você defina um valor fixo para o segredo da semente de hash.

  Novo na versão 3.2.3.

`-s```

  Não adiciona o `diretório de site-packages de usuário ` a :data:`sys.path`.

  Ver também

  PEP 370 – Diretório site-packages por usuário.

`-S```

  Desabilita a importação do módulo `site` e as manipulações dependentes do site de :data:` sys.path` que isso acarreta. Também desabilita essas manipulações se `site` for explicitamente importado mais tarde (chame `site.main()` se você quiser que eles sejam acionados).

`-u```

  Force the binary layer of the stdout and stderr streams (which is available as their `buffer` attribute) to be unbuffered. The text I/O layer will still be line-buffered if writing to the console, or block-buffered if redirected to a non-interactive file.

  Veja também `PYTHONUNBUFFERED`.

`-v```

  Exibe uma mensagem cada vez que um módulo é inicializado, mostrando o local (nome do arquivo ou módulo embutido) de onde ele é carregado. Quando fornecido duas vezes (`-vv`), imprime uma mensagem para cada arquivo que é verificado durante a busca por um módulo. Também fornece informações sobre a limpeza do módulo na saída. Veja também `PYTHONVERBOSE`.

`-W` `arg`

  Controle de aviso. O mecanismo de aviso do Python por padrão exibe mensagens de aviso para `sys.stderr`. Uma mensagem de aviso típica tem o seguinte formato:

      file:line: category: message

  Por padrão, cada aviso é exibido uma vez para cada linha fonte onde ocorre. Esta opção controla a frequência com que os avisos são exibidos.

  Várias opções `-W` podem ser fornecidas; quando um aviso corresponde a mais de uma opção, a ação para a última opção correspondente é executada. As opções `-W` inválidas são ignoradas (embora, uma mensagem de aviso seja impressa sobre opções inválidas quando o primeiro aviso for emitido).

  Warnings can also be controlled from within a Python program using the `warnings` module.

  The simplest form of argument is one of the following action strings (or a unique abbreviation):

  `ignore`

    Ignore todas as advertências..

  `default`

    Explicitly request the default behavior (printing each warning once per source line).

  `all`

    Print a warning each time it occurs (this may generate many messages if a warning is triggered repeatedly for the same source line, such as inside a loop).

  `module`

    Print each warning only the first time it occurs in each module.

  `once`

    Print each warning only the first time it occurs in the program.

  `error`

    Raise an exception instead of printing a warning message.

  A forma completa de argumento é:

      action:message:category:module:line

  Here, action is as explained above but only applies to messages that match the remaining fields. Empty fields match all values; trailing empty fields may be omitted. The message field matches the start of the warning message printed; this match is case-insensitive. The category field matches the warning category. This must be a class name; the match tests whether the actual warning category of the message is a subclass of the specified warning category. The full class name must be given. The module field matches the (fully-qualified) module name; this match is case-sensitive. The line field matches the line number, where zero matches all line numbers and is thus equivalent to an omitted line number.

  Ver também

  `warnings` – the warnings module

  PEP 230 – Warning framework

  `PYTHONWARNINGS`

`-x```

  Pula a primeira linha do código-fonte, permitindo o uso de formas não-Unix de `#!cmd`. Isso se destina apenas a um hack específico do DOS.

`-X```

  Reservado para várias opções específicas de implementação. CPython atualmente define os seguintes valores possíveis:

  - `-X faulthandler` para habilitar `faulthandler`;

  - `-X showrefcount` para produzir a contagem de referências total e o número de blocos de memória usados ​​quando o programa termina ou após cada instrução no interpretador interativo. Isso só funciona em compilações de depuração.

  - `-X tracemalloc` para começar a rastrear alocações de memória do Python usando o módulo `tracemalloc`. Por padrão, apenas o quadro mais recente é armazenado no traceback (situação da pilha de execução) de um rastro. Use `-X tracemalloc=NFRAME` para iniciar o rastreamento com um limite de traceback de quadros NFRAME. Veja o `tracemalloc.start()` para mais informações.

  - `-X showalloccount` to output the total count of allocated objects for each type when the program finishes. This only works when Python was built with `COUNT_ALLOCS` defined.

  Também permite passar valores arbitrários e recuperá-los através do dicionário `sys._xoptions`.

  Alterado na versão 3.2: A opção `-X` foi adicionada.

  Novo na versão 3.3: A opção `-X faulthandler` .

  Novo na versão 3.4: As opções `-X showrefcount` e `-X tracemalloc` .

  Novo na versão 3.6: A opção `-X showalloccount` .

### 1.1.4. Opções que você não deve usar

`-J```

  Reservado para uso pelo Jython.

## 1.2. Variáveis de ambiente

Essas variáveis de ambiente influenciam o comportamento do Python, elas são processadas antes das opções de linha de comando diferentes de -E ou -I. É comum que as opções de linha de comando substituam as variáveis ambientais onde há um conflito.

`PYTHONHOME`

  Altera a localização das bibliotecas Python padrão. Por padrão, as bibliotecas são pesquisadas em `prefix/lib/pythonversion` e `exec_prefix/lib/pythonversion`, onde `prefix` e `exec_prefix` são diretórios dependentes da instalação, ambos padronizando para `/usr/local`.

  Quando `PYTHONHOME` é definido como um único diretório, seu valor substitui `prefix` e `exec_prefix`. Para especificar valores diferentes para estes, defina `PYTHONHOME` para `prefix:exec_prefix`.

`PYTHONPATH`

  Aumenta o caminho de pesquisa padrão para arquivos de módulo. O formato é o mesmo `PATH` do shell: um ou mais caminhos de diretório separados por `os.pathsep` (por exemplo, dois pontos no Unix ou ponto e vírgula no Windows). Os diretórios inexistentes são ignorados silenciosamente.

  Além dos diretórios normais, entradas individuais `PYTHONPATH` podem referir-se a arquivos zip contendo módulos Python puros (tanto no código-fonte quanto na forma compilada). Módulos de extensão não podem ser importados de arquivos zip.

  O caminho de pesquisa padrão depende da instalação, mas geralmente começa com `prefix/lib/pythonversion` (veja `PYTHONHOME` acima). É sempre anexado a `PYTHONPATH`.

  Um diretório adicional será inserido no caminho de pesquisa antes de `PYTHONPATH` como descrito acima em Opções de interface. O caminho de pesquisa pode ser manipulado de dentro de um programa Python como a variável `sys.path`.

`PYTHONSTARTUP`

  Se este for o nome de um arquivo legível, os comandos Python nesse arquivo serão executados antes que o primeiro prompt seja exibido no modo interativo. O arquivo é executado no mesmo namespace onde os comandos interativos são executados para que os objetos definidos ou importados nele possam ser usados sem qualificação na sessão interativa. Você também pode alterar os prompts `sys.ps1` e `sys.ps2` e o gancho `sys.__interactivehook__` neste arquivo.

`PYTHONOPTIMIZE`

  Se for definido como uma string não vazia, é equivalente a especificar a opção `-O`. Se definido como um inteiro, é equivalente a especificar `-O` várias vezes.

`PYTHONDEBUG`

  Se for definido como uma string não vazia, é equivalente a especificar a opção `-d`. Se definido como um inteiro, é equivalente a especificar `-d` várias vezes.

`PYTHONINSPECT`

  Se for definido como uma string não vazia, é equivalente a especificar a opção `-i`.

  Esta variável também pode ser modificada pelo código Python usando `os.environ` para forçar o modo de inspeção no encerramento do programa.

`PYTHONUNBUFFERED`

  Se for definido como uma string não vazia, é equivalente a especificar a opção `-u`.

`PYTHONVERBOSE`

  Se for definido como uma string não vazia, é equivalente a especificar a opção `-v`. Se definido como um inteiro, é equivalente a especificar `-v` várias vezes.

`PYTHONCASEOK`

  Se estiver definido, Python não diferencia letras maiúsculas e minúsculas nas instruções `import`. Isso só funciona no Windows e OS X.

`PYTHONDONTWRITEBYTECODE`

  Se for definido como uma string não vazia, o Python não tentará escrever arquivos `.pyc` na importação de módulos fonte. Isso é equivalente a especificar a opção `-B`.

`PYTHONHASHSEED`

  If this variable is not set or set to `random`, a random value is used to seed the hashes of str, bytes and datetime objects.

  Se `PYTHONHASHSEED` for definido como um valor inteiro, ele é usado como uma semente fixa para gerar o hash() dos tipos cobertos pela aleatorização do hash.

  Sua finalidade é permitir hash repetível, como autotestes do próprio interpretador, ou permitir que um cluster de processos Python compartilhe valores de hash.

  O número inteiro deve ser um número decimal no intervalo [0,4294967295]. Especificar o valor 0 desabilitará a aleatorização de hash.

  Novo na versão 3.2.3.

`PYTHONIOENCODING`

  Se for definido antes de executar o interpretador, ele substitui a codificação usada para stdin/stdout/stderr, na sintaxe `encodingname:errorhandler`. Ambas as partes `encodingname` e `:errorhandler` são opcionais e têm o mesmo significado que em `str.encode()`.

  Para stderr, a parte `:errorhandler` é ignorada; o tratador sempre será `'backslashreplace'`.

  Alterado na versão 3.4: A parte `encodingname` é agora opcional.

  Alterado na versão 3.6: No Windows, a codificação especificada por esta variável é ignorada para buffers de console interativo, a menos que `PYTHONLEGACYWINDOWSSTDIO` também seja especificado. Arquivos e canais redirecionados por meio de fluxos padrão não são afetados.

`PYTHONNOUSERSITE`

  Se estiver definido, o Python não adicionará o `user site-packages directory ` a :data:`sys.path`.

  Ver também

  PEP 370 – Diretório site-packages por usuário.

`PYTHONUSERBASE`

  Define o `diretório base do usuário`, que é usado para calcular o caminho do `diretório site-packages do usuário` e caminhos de instalação do Distutils para `python setup.py install --user`.

  Ver também

  PEP 370 – Diretório site-packages por usuário.

`PYTHONEXECUTABLE`

  Se esta variável de ambiente for definida, `sys.argv[0]` será definido com seu valor em vez do valor obtido através do tempo de execução C. Funciona apenas no Mac OS X.

`PYTHONWARNINGS`

  This is equivalent to the `-W` option. If set to a comma separated string, it is equivalent to specifying `-W` multiple times.

`PYTHONFAULTHANDLER`

  Se esta variável de ambiente for definida como uma string não vazia, `faulthandler.enable()` é chamado na inicialização: instale um tratador para os sinais `SIGSEGV`, `SIGFPE`, `SIGABRT`, `SIGBUS` and `SIGILL` para despejar o traceback (situação da pilha de execução) do Python. Isso é equivalente à opção `-X` `faulthandler`.

  Novo na versão 3.3.

`PYTHONTRACEMALLOC`

  Se esta variável de ambiente for definida como uma string não vazia, começa a rastrear as alocações de memória Python usando o módulo `tracemalloc`. O valor da variável é o número máximo de quadros armazenados em um traceback de um rastreamento. Por exemplo, `PYTHONTRACEMALLOC=1` armazena apenas o quadro mais recente. Veja o `tracemalloc.start()` para mais informações.

  Novo na versão 3.4.

`PYTHONASYNCIODEBUG`

  Se esta variável de ambiente for definida como uma string não vazia, habilita o modo de depuração do módulo `asyncio`.

  Novo na versão 3.4.

`PYTHONMALLOC`

  Define os alocadores de memória Python e/ou instale ganchos de depuração.

  Define a família de alocadores de memória usados ​​pelo Python:

  - `malloc`: usa a função `malloc()` da biblioteca C para todos os domínios (`PYMEM_DOMAIN_RAW`, `PYMEM_DOMAIN_MEM`, `PYMEM_DOMAIN_OBJ`).

  - `pymalloc`: usa o alocador pymalloc para domínios `PYMEM_DOMAIN_MEM` e `PYMEM_DOMAIN_OBJ` e usa a função `malloc()` para o domínio `PYMEM_DOMAIN_RAW`.

  Instala os ganchos de depuração:

  - `debug`: install debug hooks on top of the default memory allocator

  - `malloc_debug`: same as `malloc` but also install debug hooks

  - `pymalloc_debug`: same as `pymalloc` but also install debug hooks

  When Python is compiled in release mode, the default is `pymalloc`. When compiled in debug mode, the default is `pymalloc_debug` and the debug hooks are used automatically.

  If Python is configured without `pymalloc` support, `pymalloc` and `pymalloc_debug` are not available, the default is `malloc` in release mode and `malloc_debug` in debug mode.

  See the `PyMem_SetupDebugHooks()` function for debug hooks on Python memory allocators.

  Novo na versão 3.6.

`PYTHONMALLOCSTATS`

  Se definido como uma string não vazia, o Python exibe estatísticas do alocador de memória pymalloc toda vez que uma nova arena de objeto pymalloc for criada e ao no desligamento.

  Esta variável é ignorada se a variável de ambiente `PYTHONMALLOC` é usada para forçar o alocador `malloc()` da biblioteca C, ou se Python está configurado sem suporte a `pymalloc`.

  Alterado na versão 3.6: Esta variável agora também pode ser usada em Python compilado no modo de lançamento. Agora não tem efeito se definido como uma string vazia.

`PYTHONLEGACYWINDOWSFSENCODING`

  Se definido como uma string não vazia, a codificação do sistema de arquivos padrão e o modo de erros serão revertidos para seus valores pré-3.6 de “mbcs” e “replace”, respectivamente. Caso contrário, os novos padrões “utf-8” e “surrogatepass” serão usados.

  Isso também pode ser habilitado em tempo de execução com `sys._enablelegacywindowsfsencoding()`.

  Availability: Windows

  Novo na versão 3.6: Veja PEP 529 para mais detalhes.

`PYTHONLEGACYWINDOWSSTDIO`

  Se definido como uma string não vazia, não usa o novo leitor e escritor de console. Isso significa que os caracteres Unicode serão codificados de acordo com a página de código do console ativo, em vez de usar utf-8.

  Esta variável é ignorada se os fluxos padrão forem redirecionados (para arquivos ou canais) em vez de se referir aos buffers do console.

  Availability: Windows

  Novo na versão 3.6.

### 1.2.1. Variáveis de modo de depuração

Setting these variables only has an effect in a debug build of Python, that is, if Python was configured with the `--with-pydebug` build option.

`PYTHONTHREADDEBUG`

  Se definido, Python exibirá informações de depuração de threads.

`PYTHONDUMPREFS`

  Se definido, Python irá despejar objetos e contagens de referências ainda vivas após desligar o interpretador.