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.
Detalhes da implementação do CPython: 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 desys.path
(permitindo módulos nesse diretório para ser importado como módulos de nível superior).Levanta um evento de auditoria
cpython.run_command
com argumentocommand
.
- -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 desys.path
.-I
option can be used to run the script in isolated mode wheresys.path
contains neither the current directory nor the user’s site-packages directory. AllPYTHON*
environment variables are ignored, too.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 -m timeit -s 'setup here' 'benchmarked code here' python -m timeit -h # for details
Levanta um evento de auditoria
cpython.run_module
com argumentomodule-name
.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 desys.path
.Levanta um evento de auditoria
cpython.run_stdin
com nenhum argumento.
- <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__
.-I
option can be used to run the script in isolated mode wheresys.path
contains neither the script’s directory nor the user’s site-packages directory. AllPYTHON*
environment variables are ignored, too.Levanta um evento de auditoria
cpython.run_file
com argumentofilename
.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
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 e variáveis de ambiente correspondentes e sai.
- --help-env¶
Imprime uma breve descrição das variáveis de ambiente específicas do Python e sai.
Novo na versão 3.11.
- --help-xoptions¶
Imprime uma descrição das opções
-X
específica da implementação e sai.Novo na versão 3.11.
- --help-all¶
Imprime as informações de uso completas e sai.
Novo na versão 3.11.
1.1.3. Opções diversas¶
- -b¶
Issue a warning when converting
bytes
orbytearray
tostr
without specifying encoding or comparingbytes
orbytearray
withstr
orbytes
withint
. Issue an error when the option is given twice (-bb
).
- -B¶
Se fornecido, Python não tentará escrever arquivos
.pyc
na importação de módulos fonte. Veja tambémPYTHONDONTWRITEBYTECODE
.
- --check-hash-based-pycs default|always|never¶
Controla o comportamento de validação de arquivos
.pyc
baseados em hash. Veja Cached bytecode invalidation. Quando definido comodefault
, os arquivos de cache bytecode baseados em hash verificados e não verificados são validados de acordo com sua semântica padrão. Quando definido comoalways
, todos os arquivos.pyc
baseados em hash, sejam verificados ou não verificados, são validados para seus arquivos fonte correspondentes. Quando definido comonever
, os arquivos.pyc
baseados em hash não são validados para seus arquivos fonte correspondentes.A semântica dos arquivos
.pyc
baseados em marca de tempo não é afetada por esta opção.
- -d¶
Ativa a saída de depuração do analisador sintático (apenas para especialistas, dependendo das opções de compilação). Veja também
PYTHONDEBUG
.
- -E¶
Ignore all
PYTHON*
environment variables, e.g.PYTHONPATH
andPYTHONHOME
, that might be set.
- -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 quandosys.stdin
não parece ser um terminal. O arquivoPYTHONSTARTUP
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 nas opções
-E
,-P
e-s
.In isolated mode
sys.path
contains neither the script’s directory nor the user’s site-packages directory. AllPYTHON*
environment variables are ignored, too. Further restrictions may be imposed to prevent the user from injecting malicious code.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émPYTHONOPTIMIZE
.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.
- -P¶
Não anexa um caminho potencialmente inseguro a
sys.path
:A linha de comando
python -m módulo
: Não anexa o diretório atual.A linha de comando
python script.py
: não anexa o diretório do script. Se for um link simbólico, resolve os links simbólicos.Linhas de comando
python -c código
epython
(REPL): Não anexa uma string vazia, o que significa o diretório de trabalho atual.
Veja também a variável de ambiente
PYTHONSAFEPATH
e as opções-E
e-I
(isolado).Novo na versão 3.11.
- -q¶
Não exibe as mensagens de copyright e de versão nem mesmo no modo interativo.
Novo na versão 3.2.
- -R¶
Habilita a aleatorização com hash. Esta opção só tem efeito se a variável de ambiente
PYTHONHASHSEED
estiver configurada para0
, uma vez que a aleatorização com hash é habilitada por padrão.On previous versions of Python, this option turns on hash randomization, so that the
__hash__()
values of str and bytes objects 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.Hash randomization is intended to provide protection against a denial-of-service caused by carefully chosen inputs that exploit the worst case performance of a dict construction, O(n2) complexity. See http://ocert.org/advisories/ocert-2011-003.html for details.
PYTHONHASHSEED
permite que você defina um valor fixo para o segredo da semente de hash.Novo na versão 3.2.3.
Alterado na versão 3.7: A opção não é mais ignorada.
- -s¶
Não adiciona o
diretório site-packages de usuário
asys.path
.See also
PYTHONNOUSERSITE
.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 desys.path
que isso acarreta. Também desabilita essas manipulações sesite
for explicitamente importado mais tarde (chamesite.main()
se você quiser que eles sejam acionados).
- -u¶
Força os fluxos stdout e stderr a serem sem buffer. Esta opção não tem efeito no fluxo stdin.
Veja também
PYTHONUNBUFFERED
.Alterado na versão 3.7: A camada de texto dos fluxos stdout e stderr agora é sem buffer.
- -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
), exibe 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.Alterado na versão 3.10: O módulo
site
relata os caminhos específicos do site e os arquivos.pth
sendo processados.Veja também
PYTHONVERBOSE
.
- -W arg¶
Controle de advertência. O mecanismo de aviso do Python por padrão exibe mensagens de aviso para
sys.stderr
.As configurações mais simples aplicam uma determinada ação incondicionalmente a todos os avisos emitidos por um processo (mesmo aqueles que são ignorados por padrão):
-Wdefault # Warn once per call location -Werror # Convert to exceptions -Walways # Warn every time -Wmodule # Warn once per calling module -Wonce # Warn once per Python process -Wignore # Never warn
Os nomes das ações podem ser abreviados conforme desejado e o interpretador irá resolvê-los para o nome da ação apropriado. Por exemplo,
-Wi
é o mesmo que-Wignore
.A forma completa de argumento é:
action:message:category:module:lineno
Os campos vazios correspondem a todos os valores; campos vazios à direita podem ser omitidos. Por exemplo,
-W ignore::DeprecationWarning
ignora todos os avisos de DeprecationWarning.O campo action é explicado acima, mas se aplica apenas a avisos que correspondem aos campos restantes.
O campo message deve corresponder a toda a mensagem de aviso; essa correspondência não diferencia maiúsculas de minúsculas.
O campo category corresponde à categoria de aviso (ex:
DeprecationWarning
). Deve ser um nome de classe; o teste de correspondência se a categoria de aviso real da mensagem é uma subclasse da categoria de aviso especificada.O campo module corresponde ao nome do módulo (totalmente qualificado); esta correspondência diferencia maiúsculas de minúsculas.
O campo lineno corresponde ao número da linha, onde zero corresponde a todos os números da linha e, portanto, é equivalente a um número da linha omitido.
Múltiplas 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 exibida sobre opções inválidas quando o primeiro aviso for emitido).Os avisos também podem ser controlados usando a variável de ambiente
PYTHONWARNINGS
e de dentro de um programa Python usando o módulowarnings
. Por exemplo, a funçãowarnings.filterwarnings()
pode ser usada para usar uma expressão regular na mensagem de aviso.Veja O filtro de avisos e Describing Warning Filters para mais detalhes.
- -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 habilitarfaulthandler
. Veja tambémPYTHONFAULTHANDLER
.-X showrefcount
para emitir 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 construções de depuração.-X tracemalloc
para começar a rastrear alocações de memória do Python usando o módulotracemalloc
. 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 otracemalloc.start()
ePYTHONTRACEMALLOC
para mais informações.-X int_max_str_digits
configura a limitação de comprimento de string na conversão para inteiro. Veja tambémPYTHONINTMAXSTRDIGITS
.-X importtime
para mostrar quanto tempo leva cada importação. Mostra o nome do módulo, tempo cumulativo (incluindo importações aninhadas) e tempo próprio (excluindo importações aninhadas). Observe que sua saída pode ser interrompida em aplicações multithread. O uso típico épython3 -X importtime -c 'import asyncio'
. Veja tambémPYTHONPROFILEIMPORTTIME
.-X dev
: enable Python Development Mode, introducing additional runtime checks that are too expensive to be enabled by default. See alsoPYTHONDEVMODE
.-X utf8
habilita o Modo UTF-8 do Python.-X utf8=0
explicitamente desabilita o Modo UTF-8 do Python (mesmo quando de outra forma seria ativado automaticamente). Veja tambémPYTHONUTF8
.-X pycache_prefix=PATH
permite a escrita de arquivos.pyc
em uma árvore paralela enraizada em um determinado diretório em vez de na árvore de código. Veja tambémPYTHONPYCACHEPREFIX
.-X warn_default_encoding
emite umaEncodingWarning
quando a codificação padrão específica da localidade é usada para abrir arquivos. Veja tambémPYTHONWARNDEFAULTENCODING
.-X no_debug_ranges
desabilita a inclusão das tabelas que mapeiam informações de localização extra (linha final, deslocamento da coluna inicial e deslocamento da coluna final) para cada instrução em objetos código. Isso é útil quando objetos código menores e arquivos pyc são desejados, bem como suprimir os indicadores de localização visual extra quando o interpretador exibe tracebacks. Veja tambémPYTHONNODEBUGRANGES
.-X frozen_modules
determina se os módulos congelados são ou não ignorados pelo maquinário de importação. Um valor de “on” significa que eles são importados e “off” significa que eles são ignorados. O padrão é “on” se este for um Python instalado (o caso normal). Se estiver em desenvolvimento (executando a partir da árvore de origem), o padrão é “off”. Observe que os módulos congelados “importlib_bootstrap” e “importlib_bootstrap_external” são sempre usados, mesmo que esse sinalizador esteja definido como “off”.
Também permite passar valores arbitrários e recuperá-los através do dicionário
sys._xoptions
.Novo na versão 3.2.
Alterado na versão 3.3: Added the
-X faulthandler
option.Alterado na versão 3.4: Added the
-X showrefcount
and-X tracemalloc
options.Alterado na versão 3.6: Added the
-X showalloccount
option.Alterado na versão 3.7: Added the
-X importtime
,-X dev
and-X utf8
options.Alterado na versão 3.8: Added the
-X pycache_prefix
option. The-X dev
option now logsclose()
exceptions inio.IOBase
destructor.Alterado na versão 3.9: Usando a opção
-X dev
, verifica os argumentos de encoding e errors nas operações de codificação e decodificação de strings.A opção
-X showalloccount
foi removida.Alterado na versão 3.10: Added the
-X warn_default_encoding
option. Removed the-X oldparser
option.Alterado na versão 3.11: Added the
-X no_debug_ranges
,-X frozen_modules
and-X int_max_str_digits
options.
1.1.4. Opções que você não deve usar¶
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
eexec_prefix/lib/pythonversion
, ondeprefix
eexec_prefix
são diretórios dependentes da instalação, ambos padronizando para/usr/local
.Quando
PYTHONHOME
é definido como um único diretório, seu valor substituiprefix
eexec_prefix
. Para especificar valores diferentes para estes, definaPYTHONHOME
paraprefix: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 poros.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
(vejaPYTHONHOME
acima). É sempre anexado aPYTHONPATH
.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ávelsys.path
.
- PYTHONSAFEPATH¶
Se for definido como uma string não vazia, não anexa um caminho potencialmente inseguro para
sys.path
: consulte a opção-P
para obter detalhes.Novo na versão 3.11.
- PYTHONPLATLIBDIR¶
Se for definido como uma string não vazia, ela substitui o valor
sys.platlibdir
.Novo na versão 3.9.
- 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
esys.ps2
e o ganchosys.__interactivehook__
neste arquivo.Levanta um evento de auditoria
cpython.run_startup
com argumentofilename
.
- 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.
- PYTHONBREAKPOINT¶
Se estiver definida, ela nomeia um chamável usando a notação de caminho com pontos. O módulo que contém o chamável será importado e então o chamável será executado pela implementação padrão de
sys.breakpointhook()
que é chamado pelobreakpoint()
embutido. Se não for definido, ou definido como uma string vazia, é equivalente ao valor “pdb.set_trace”. Definir isso para a string “0” faz com que a implementação padrão desys.breakpointhook()
não faça nada além de retornar imediatamente.Novo na versão 3.7.
- 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
.
- PYTHONPYCACHEPREFIX¶
Se estiver definido, o Python escreverá os arquivos
.pyc
em uma árvore de diretório espelho neste caminho, em vez de nos diretórios__pycache__
dentro da árvore de fontes. Isso é equivalente a especificar a opção-X
pycache_prefix=PATH
.Novo na versão 3.8.
- PYTHONHASHSEED¶
Se esta variável não for definida ou definida como
random
, um valor aleatório é usado para semear os hashes de objetos str e bytes.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.
- PYTHONINTMAXSTRDIGITS¶
Se esta variável estiver definida para um inteiro, é usada para configurar a limitação de comprimento de string na conversão para inteiro global do interpretador.
Novo na versão 3.11.
- 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 partesencodingname
e:errorhandler
são opcionais e têm o mesmo significado que emstr.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
diretório site-packages de usuário
asys.path
.Ver também
PEP 370 – Diretório site-packages por usuário.
- PYTHONUSERBASE¶
Defines the
user base directory
, which is used to compute the path of theuser site-packages directory
and installation paths forpython -m pip 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 macOS.
- PYTHONWARNINGS¶
Isso é equivalente à opção
-W
. Se definido como uma string separada por vírgulas, é equivalente a especificar-W
várias vezes, com os filtros posteriores na lista tendo precedência sobre os anteriores na lista.As configurações mais simples aplicam uma determinada ação incondicionalmente a todos os avisos emitidos por um processo (mesmo aqueles que são ignorados por padrão):
PYTHONWARNINGS=default # Warn once per call location PYTHONWARNINGS=error # Convert to exceptions PYTHONWARNINGS=always # Warn every time PYTHONWARNINGS=module # Warn once per calling module PYTHONWARNINGS=once # Warn once per Python process PYTHONWARNINGS=ignore # Never warn
Veja O filtro de avisos e Describing Warning Filters para mais detalhes.
- PYTHONFAULTHANDLER¶
If this environment variable is set to a non-empty string,
faulthandler.enable()
is called at startup: install a handler forSIGSEGV
,SIGFPE
,SIGABRT
,SIGBUS
andSIGILL
signals to dump the Python traceback. This is equivalent to-X
faulthandler
option.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 a funçãotracemalloc.start()
para mais informações. Isso é o equivalente a definir a opção-X
tracemalloc
.Novo na versão 3.4.
- PYTHONPROFILEIMPORTTIME¶
Se esta variável de ambiente for definida como uma string não vazia, o Python mostrará quanto tempo leva cada importação. Isso é o equivalente a definir a opção
-X
importtime
.Novo na versão 3.7.
- 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:
default
: usa os alocadores padrão de memória.malloc
: use themalloc()
function of the C library for all domains (PYMEM_DOMAIN_RAW
,PYMEM_DOMAIN_MEM
,PYMEM_DOMAIN_OBJ
).pymalloc
: use the pymalloc allocator forPYMEM_DOMAIN_MEM
andPYMEM_DOMAIN_OBJ
domains and use themalloc()
function for thePYMEM_DOMAIN_RAW
domain.
Instala ganchos de depuração:
debug
: instala os ganchos de depuração sobre os alocadores padrão de memória.malloc_debug
: o mesmo quemalloc
, mas também instala ganchos de depuração.pymalloc_debug
: o mesmo quepymalloc
, mas também instala ganchos de depuração.
Novo na versão 3.6.
Alterado na versão 3.7: Adicionado o alocador
"default"
.
- 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 alocadormalloc()
da biblioteca C, ou se Python está configurado sem suporte apymalloc
.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, o modo padrão do tratador de erros e codificação do sistema de arquivos irá reverter 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()
.Disponibilidade: 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.
Disponibilidade: Windows.
Novo na versão 3.6.
- PYTHONCOERCECLOCALE¶
Se definido com o valor
0
, faz com que a aplicação principal de linha de comando Python ignore a coerção dos códigos de idioma legados C e POSIX baseados em ASCII para uma alternativa baseada em UTF-8 mais capaz.Se esta variável não estiver definida (ou estiver definida para um valor diferente de
0
), a variável de ambiente de substituição de localidadeLC_ALL
também não será definida, e a localidade atual relatada para a categoriaLC_CTYPE
é a localidadeC
padrão, ou então a localidadePOSIX
explicitamente baseada em ASCII, então a CLI do Python tentará configurar as seguintes localidades para a categoriaLC_CTYPE
na ordem listada antes de carregar o tempo de execução do interpretador:C.UTF-8
C.utf8
UTF-8
Se a configuração de uma dessas categorias de local for bem-sucedida, a variável de ambiente
LC_CTYPE
também será configurada de acordo no ambiente de processo atual antes que o tempo de execução do Python seja inicializado. Isso garante que, além de ser visto pelo próprio interpretador e outros componentes com reconhecimento de localidade em execução no mesmo processo (como a biblioteca GNUreadline
), a configuração atualizada também é vista em subprocessos (independentemente de ou não esses processos estão executando um interpretador Python), bem como em operações que consultam o ambiente em vez da localidade C atual (como olocale.getdefaultlocale()
do próprio Python).Configurar uma dessas localidades (explicitamente ou por meio da coerção de localidade implícita acima) habilita automaticamente o tratador de erros
surrogateescape
parasys.stdin
esys.stdout
(sys.stderr
continua a usarbackslashreplace
como faz em qualquer outra localidade). Este comportamento de tratamento de fluxo pode ser substituído usandoPYTHONIOENCODING
como de costume.Para fins de depuração, definir
PYTHONCOERCECLOCALE=warn
fará com que o Python emita mensagens de aviso emstderr
se a coerção de localidade for ativada ou se uma localidade que teria acionado a coerção ainda estiver ativa quando o Python o tempo de execução é inicializado.Observe também que mesmo quando a coerção de localidade está desabilitada, ou quando não consegue encontrar uma localidade de destino adequada,
PYTHONUTF8
ainda será ativado por padrão em localidades baseadas em ASCII legadas. Ambos os recursos devem ser desabilitados para forçar o interpretador a usarASCII
ao invés deUTF-8
para interfaces de sistema.Disponibilidade: Unix.
Novo na versão 3.7: Veja PEP 538 para mais detalhes.
- PYTHONDEVMODE¶
Se esta variável de ambiente for definida como uma string não vazia, habilita Modo de Desenvolvimento do Python, introduzindo verificações adicionais de tempo de execução que são muito caras para serem habilitadas por padrão. Isso é o equivalente a definir a opção
-X
dev
.Novo na versão 3.7.
- PYTHONUTF8¶
Se definido para
1
, habilita o modo UTF-8 do Python.Se definido para
0
, desabilita o modo UTF-8 do Python.Definir qualquer outra string não vazia causa um erro durante a inicialização do interpretador.
Novo na versão 3.7.
- PYTHONWARNDEFAULTENCODING¶
Se esta variável de ambiente for definida como uma string não vazia, emite uma
EncodingWarning
quando a codificação padrão específica da localidade é usada.Veja Opt-in EncodingWarning para detalhes.
Novo na versão 3.10.
- PYTHONNODEBUGRANGES¶
Se esta variável estiver definida, ela desabilita a inclusão das tabelas que mapeiam informações de localização extra (linha final, deslocamento da coluna inicial e deslocamento da coluna final) para cada instrução em objetos código. Isso é útil quando objetos código menores e arquivos pyc são desejados, bem como suprimir os indicadores de localização visual extra quando o interpretador exibe tracebacks.
Novo na versão 3.11.
1.2.1. Variáveis de modo de depuração¶
- PYTHONTHREADDEBUG¶
Se definido, Python exibe informações de depuração de threading no stdout.
Necessita de uma construção de depuração do Python.
Descontinuado desde a versão 3.10, será removido na versão 3.12.
- PYTHONDUMPREFS¶
Se definido, Python irá despejar objetos e contagens de referências ainda vivas após desligar o interpretador.
Necessita do Python configurado com a opção de construção
--with-trace-refs
.
- PYTHONDUMPREFSFILE=FILENAME¶
Se definido, Python irá despejar objetos e contagens de referências ainda vivas após desligar o interpretador em um arquivo chamado FILENAME.
Necessita do Python configurado com a opção de construção
--with-trace-refs
.Novo na versão 3.11.