1. Ligne de commande et environnement¶
L'interpréteur CPython analyse la ligne de commande et l'environnement à la recherche de différents paramètres.
Particularité de l'implémentation CPython : Le format des lignes de commande utilisé par d'autres implémentations peut s'avérer différent. Voir Autres implémentations pour plus d'informations.
1.1. Ligne de commande¶
Quand vous invoquez Python, vous pouvez spécifier n’importe laquelle de ces options :
python [-bBdEhiIOPqRsSuvVWx?] [-c command | -m module-name | script | - ] [args]
Le cas d'utilisation le plus courant est, bien entendu, la simple invocation d'un script :
python myscript.py
1.1.1. Options de l'interface¶
L'interface de l’interpréteur ressemble à celle du shell UNIX mais fournit quelques méthodes d'invocation supplémentaires :
When called with standard input connected to a tty device, it prompts for commands and executes them until an EOF (an end-of-file character, you can produce that with Ctrl-D on UNIX or Ctrl-Z, Enter on Windows) is read. For more on interactive mode, see Mode interactif.
Quand l'interpréteur est appelé avec un argument correspondant à un nom de fichier ou avec un fichier comme entrée standard, il lit et exécute le script contenu dans ce fichier.
Quand l'interpréteur est appelé avec un argument correspondant à un répertoire, il lit et exécute un script d’un certain nom dans ce répertoire.
Quand l'interpréteur est appelé avec l'option
-c commande
, il exécute la ou les instructions Python données comme commande. Ici commande peut contenir plusieurs instructions séparées par des fins de ligne. Les blancs en début de ligne ne sont pas ignorés dans les instructions Python !Quand l'interpréteur est appelé avec l'option
-m nom-de-module
, le module donné est recherché dans le chemin des modules Python et est exécuté en tant que script.
En mode non-interactif, toute l’entrée est analysée avant d’être exécutée.
Une option d'interface termine la liste des options consommées par l'interpréteur ; tous les arguments atterrissent dans sys.argv
— notez que le premier élément, à l'indice zéro (sys.argv|0]
), est une chaîne de caractères indiquant la source du programme.
- -c <command>¶
Exécute le code Python dans command. command peut être une ou plusieurs instructions, séparées par des fins de ligne, dont les espaces en début de ligne sont significatives, comme dans le code d’un module.
Si cette option est donnée, le premier élément de
sys.argv
est"-c"
et le répertoire courant est ajouté au début desys.path
(permettant aux modules de ce répertoire d'être importés comme des modules de premier niveau).Lève un évènement d'audit
cpython.run_command
avec comme argumentcommand
.
- -m <module-name>¶
Parcourt
sys.path
à la recherche du module donné et exécute son contenu en tant que module__main__
.L'argument étant un nom de module, vous ne devez pas fournir d’extension de fichier (
.py
). Le nom du module doit être un nom de module Python valide, absolu, mais l'implémentation peut ne pas l'imposer (par exemple, l'utilisation d'un trait d'union peut être autorisée).Les noms de paquets sont aussi autorisés (ainsi que les paquets-espace de nommage, namespace packages en anglais). Quand un nom de paquet est donné à la place d'un simple module, l'interpréteur exécute
<pkg>.__main__
comme module principal. Ce comportement est délibérément identique au traitement d'un dossier ou d'un fichier zip donné en argument à l'interpréteur comme script.Note
Cette option ne peut pas être utilisée avec les modules natifs et les modules d'extension écrits en C, étant donné qu'ils ne possèdent pas de fichiers modules en Python. Cependant, elle peut toujours être utilisée pour les modules pré-compilés, même si le fichier source original n'est pas disponible.
Si cette option est donnée, le premier élément de
sys.argv
est le chemin complet d'accès au fichier du module (pendant que le fichier est recherché, le premier élément est mis à"-m"
). Comme avec l'option-c
, le dossier courant est ajouté au début 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.De nombreux modules de la bibliothèque standard contiennent du code qui est invoqué quand ils sont exécutés comme scripts. Un exemple est le module
timeit
:python -m timeit -s "setup here" "benchmarked code here" python -m timeit -h # for details
Lève un évènement d'audit
cpython.run_command
avec comme argumentmodule-name
.Voir aussi
runpy.run_module()
Fonctionnalité équivalente directement disponible en code Python
PEP 338 -- Exécuter des modules en tant que scripts
Modifié dans la version 3.1: Fournir le nom d'un paquet pour exécuter un sous-module
__main__
.Modifié dans la version 3.4: les paquets-espaces de nommage sont aussi gérés
- -
Lit les commandes depuis l'entrée standard (
sys.stdin
). Si l'entrée standard est un terminal, l'option-i
est activée implicitement.Si cette option est donnée, le premier élément de
sys.argv
est"-"
et le dossier courant est ajouté au début desys.path
.Lève un évènement d'audit
cpython.run_stdin
sans argument.
- <script>
Exécute le code Python contenu dans script, qui doit être un chemin d'accès (absolu ou relatif) à un fichier, faisant référence à un fichier Python, à un répertoire contenant un fichier
__main__.py
ou à un fichier zip contenant un fichier__main__.py
.Si cette option est donnée, le premier élément de
sys.argv
est le nom du script tel que donné sur la ligne de commande.Si le nom du script se réfère directement à un fichier Python, le répertoire contenant ce fichier est ajouté au début de
sys.path
et le fichier est exécuté en tant que module__main__
.Si le nom du script fait référence à un dossier ou à un fichier zip, le nom du script est ajouté au début de
sys.path
et le fichier__main__.py
à cet endroit est exécuté en tant que module__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.Lève un évènement d'audit
cpython.run_file
avec comme argumentfilename
.Voir aussi
runpy.run_path()
Fonctionnalité équivalente directement disponible en code Python
Si aucune option d'interface n'est donnée, l'option -i
est activée implicitement, sys.argv[0]
est une chaine vide (""
) et le dossier courant est ajouté au début de sys.path
. Aussi, la complétion par tabulation et l'édition de l'historique sont automatiquement activés, s'ils sont disponibles sur votre système (voir Readline configuration).
Voir aussi
Modifié dans la version 3.4: Activation automatique de la complétion par tabulation et édition de l'historique.
1.1.2. Options génériques¶
- -?¶
- -h¶
- --help¶
Affiche une brève description de toutes les options de la ligne de commande et des variables d'environnement correspondantes, puis quitte.
- --help-env¶
Affiche une brève description des variables d'environnement spécifiques à Python et quitte.
Ajouté dans la version 3.11.
- --help-xoptions¶
Affiche une description spécifique à l'implémentation des options
-X
et quitte.Ajouté dans la version 3.11.
- --help-all¶
Affiche toutes les informations d'utilisation et quitte.
Ajouté dans la version 3.11.
- -V¶
- --version¶
Affiche la version de Python et termine. Par exemple :
Python 3.8.0b2+
Lorsque l'option est doublée, affiche davantage d'informations sur la manière dont Python a été compilé, comme :
Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00) [GCC 6.2.0 20161005]
Ajouté dans la version 3.6: L'option
-VV
.
1.1.3. Options diverses¶
- -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¶
S'il est donné, Python ne tente pas d'écrire de fichier
.pyc
ou.pyo
à l'importation des modules sources. Voir aussiPYTHONDONTWRITEBYTECODE
.
- --check-hash-based-pycs default|always|never¶
Contrôle la façon dont sont validés les fichiers
.pyc
avec empreinte (voir Invalidation de bytecode mis en cache). Quand la valeur estdefault
, les caches de fichiers de code intermédiaire sont validés en fonction de leur sémantique par défaut. Quand la valeur estalways
, tous les fichiers.pyc
, qu'ils soient vérifiés ou non, sont validés par rapport à leurs fichiers sources correspondants. Quand la valeur estnever
, les fichiers.pyc
ne sont pas validés par rapport à leurs fichiers sources correspondants.La sémantique des fichiers
.pyc
générés en fonction de l'horodatage n'est pas affectée par cette option.
- -d¶
Turn on parser debugging output (for expert only). See also the
PYTHONDEBUG
environment variable.This option requires a debug build of Python, otherwise it's ignored.
- -E¶
Ignore all
PYTHON*
environment variables, e.g.PYTHONPATH
andPYTHONHOME
, that might be set.
- -i¶
Quand un script est passé comme premier argument ou que l'option
-c
est utilisée, entre en mode interactif après avoir exécuté le script ou la commande, même lorsquesys.stdin
ne semble pas être un terminal. Le fichierPYTHONSTARTUP
n'est pas lu.Cela peut être utile pour examiner les variables globales ou une trace de la pile lorsque le script lève une exception. Voir aussi
PYTHONINSPECT
.
- -I¶
Lance Python en mode isolé. Cela implique les options
-E
,-P
et-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.Ajouté dans la version 3.4.
- -O¶
Enlève les instructions assert et tout le code qui dépend de la valeur de
__debug__
. Ajoute.opt-1
au nom de fichier du code intermédiaire (bytecode), avant l'extension.pyc
(voir la PEP 488). Voir aussiPYTHONOPTIMIZE
.Modifié dans la version 3.5: Modifie les noms de fichiers
.pyc
suivant la PEP 488.
- -OO¶
Agit comme
-O
et ignore aussi les docstrings. Ajoute.opt-2
au nom de fichier du code intermédiaire (bytecode), avant l'extension.pyc
(voir la PEP 488).Modifié dans la version 3.5: Modifie les noms de fichiers
.pyc
suivant la PEP 488.
- -P¶
Ne pas ajouter de chemin (qui serait alors prioritaire) potentiellement non sûr à
sys.path
:python -m module
en ligne de commande : ne pas ajouter le répertoire de travail courant.python script.py
en ligne de commande : ne pas ajouter le répertoire du script. Si c'est un lien symbolique, résoudre les liens symboliques.python -c code
etpython
(REPL) en lignes de commande : ne pas ajouter de chaîne vide, ce qui voudrait dire le répertoire de travail courant.
Voir aussi la variable d'environnement
PYTHONSAFEPATH
ainsi que les options-E
et-I
(mode isolé).Ajouté dans la version 3.11.
- -q¶
N'affiche pas le copyright et la version, même en mode interactif.
Ajouté dans la version 3.2.
- -R¶
Active l'imprévisibilité du hachage. Cette option ne produit un effet que si la variable d'environnement
PYTHONHASHSEED
est mise à0
, puisque l'imprévisibilité du hachage est activée par défaut.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
vous permet de définir vous-même la valeur du sel pour l'algorithme de calcul des empreintes.Ajouté dans la version 3.2.3.
Modifié dans la version 3.7: Cette option n'est plus ignorée.
- -s¶
N'ajoute pas le répertoire utilisateur
site-packages
àsys.path
.See also
PYTHONNOUSERSITE
.Voir aussi
PEP 370 -- Répertoire site-packages propre à l'utilisateur
- -S¶
Désactive l’importation du module
site
et les modifications locales desys.path
qu’il implique. Désactive aussi ces manipulations sisite
est importé explicitement plus tard (appelezsite.main()
si vous voulez les déclencher).
- -u¶
Force les flux de sortie et d'erreur standards à ne pas utiliser de tampon. Cette option n'a pas d'effet sur le flux d'entrée standard.
Voir aussi
PYTHONUNBUFFERED
.Modifié dans la version 3.7: La couche texte des flux de sortie et d'erreur standards n'utilise maintenant plus de tampon.
- -v¶
Affiche un message chaque fois qu'un module est initialisé, montrant l'emplacement (nom du fichier ou module natif) à partir duquel il est chargé. Lorsque l'option est doublée (
-vv
), affiche un message pour chaque fichier vérifié lors de la recherche du module. Fournit aussi des informations sur le nettoyage des modules à la fin.Modifié dans la version 3.10: Le module
site
affiche les emplacements de recherche de modules spécifiques à l'installation ainsi que les fichiers.pth
qui sont lus.Voir aussi
PYTHONVERBOSE
.
- -W arg¶
Contrôle des avertissements. Le mécanisme d'avertissement de Python, par défaut, affiche les messages d'avertissement sur
sys.stderr
.Les configurations les plus simples forcent l'application de l'action à tous les avertissements émis par un processus (même ceux qui auraient été ignorés par défaut) :
-Wdefault # Warn once per call location -Werror # Convert to exceptions -Walways # Warn every time -Wall # Same as -Walways -Wmodule # Warn once per calling module -Wonce # Warn once per Python process -Wignore # Never warn
Les noms des actions peuvent être abrégés à votre convenance, l'interpréteur fait la résolution vers le nom adéquat. Par exemple,
-Wi
équivaut à-Wignore
.La forme développée de l'argument de
-W
est :action:message:category:module:lineno
Les champs message, category, module, line appliquent des filtres de sélection. Ils sont facultatifs : on peut les laisser vides, ou en omettre certains à la fin. Par exemple,
-W ignore::DeprecationWarning
permet d'ignorer tous les avertissements de typeDeprecationWarning
.Le champ action déjà décrit s'applique donc uniquement aux avertissements qui sont passés à travers les filtres.
Un filtre message restreint l'action aux avertissements dont le texte complet correspond à message (la comparaison ne prend pas en compte la casse).
Un filtre category restreint l'action aux avertissements dont la classe est celle nommée category, ou bien une classe fille de la classe nommée category. Un exemple pour category est
DeprecationWarning
.The module field matches the (fully qualified) module name; this match is case-sensitive.
Enfin, un filtre lineno restreint l'action aux avertissements qui proviennent d'un numéro de ligne donné. La valeur zéro revient à appliquer le filtre sur toutes les lignes, c.-à-d. l'équivalent de ne pas mettre de numéro.
L'option
-W
peut être répétée ; lorsqu'un avertissement correspond à plus d'une option, l'action associée à la dernière correspondance est effectuée. Les options-W
invalides sont ignorées (cependant, un message d'avertissement est affiché sur les options invalides au moment où le premier avertissement est généré).Les avertissements peuvent aussi être contrôlés en utilisant la variable d'environnement
PYTHONWARNINGS
et depuis un programme Python en utilisant le modulewarnings
. Par exemple, la fonctionwarnings.filterwarnings()
peut être utilisée pour filtrer les messages d'avertissement en utilisant une expression rationnelle.Voir Le filtre des avertissements et Rédaction de filtres d'avertissement pour plus de détails.
- -x¶
Saute la première ligne du code source, autorisant ainsi les directives de type
#!cmd
non conformes au standard Unix. L'objectif est de proposer une astuce spécifique pour le DOS.
- -X¶
Réservée pour les options spécifiques aux différentes implémentations. CPython reconnaît actuellement les valeurs suivantes :
-X faulthandler
to enablefaulthandler
. See alsoPYTHONFAULTHANDLER
.Ajouté dans la version 3.3.
-X showrefcount
pour afficher le compteur des références et le nombre de blocs mémoire utilisés lorsque le programme se termine ou après chaque entrée de l'interpréteur interactif. Ceci ne fonctionne que sur les versions compilées en mode débogage.Ajouté dans la version 3.4.
-X tracemalloc
to start tracing Python memory allocations using thetracemalloc
module. By default, only the most recent frame is stored in a traceback of a trace. Use-X tracemalloc=NFRAME
to start tracing with a traceback limit of NFRAME frames. Seetracemalloc.start()
andPYTHONTRACEMALLOC
for more information.Ajouté dans la version 3.4.
-X int_max_str_digits
configure la limitation de la longueur de conversion des chaînes entières. Voir aussiPYTHONINTMAXSTRDIGITS
.Ajouté dans la version 3.11.
-X importtime
affiche le temps mis pour chaque importation. Le temps total par module est affiché (y compris le temps pris par les importations imbriquées) ainsi que le temps propre du module (c.-à-d. sans les importations imbriquées). Notez que l'affichage peut être perturbé dans une application avec de multiples fils d'exécution. L'utilisation classique estpython3 -X importtime -c 'import asyncio'
. Voir aussiPYTHONPROFILEIMPORTTIME
.Ajouté dans la version 3.7.
-X dev
: enable Python Development Mode, introducing additional runtime checks that are too expensive to be enabled by default. See alsoPYTHONDEVMODE
.Ajouté dans la version 3.7.
-X utf8
enables the Python UTF-8 Mode.-X utf8=0
explicitly disables Python UTF-8 Mode (even when it would otherwise activate automatically). See alsoPYTHONUTF8
.Ajouté dans la version 3.7.
-X pycache_prefix=PATH
place l'arborescence des fichiers.pyc
à partir du chemin donné au lieu de l'arborescence du code source. Voir aussiPYTHONPYCACHEPREFIX
.Ajouté dans la version 3.8.
-X warn_default_encoding
pour émettre unEncodingWarning
lorsqu'un fichier est ouvert avec l'encodage par défaut des paramètres régionaux. Voir aussiPYTHONWARNDEFAULTENCODING
.Ajouté dans la version 3.10.
-X no_debug_ranges
désactive l'inclusion des tableaux qui font la correspondance avec des informations extérieures (ligne de fin, numéros des colonnes de début et de fin) pour toutes les instructions du code. C'est utile quand vous souhaitez diminuer la taille du code objet et des fichiers pyc ou alors quand vous voulez supprimer des informations de position quand l'interpréteur affiche les traces d'appels. Regardez aussiPYTHONNODEBUGRANGES
.Ajouté dans la version 3.11.
-X frozen_modules
determines whether or not frozen modules are ignored by the import machinery. A value ofon
means they get imported andoff
means they are ignored. The default ison
if this is an installed Python (the normal case). If it's under development (running from the source tree) then the default isoff
. Note that theimportlib_bootstrap
andimportlib_bootstrap_external
frozen modules are always used, even if this flag is set tooff
. See alsoPYTHON_FROZEN_MODULES
.Ajouté dans la version 3.11.
-X perf
enables support for the Linuxperf
profiler. When this option is provided, theperf
profiler will be able to report Python calls. This option is only available on some platforms and will do nothing if is not supported on the current system. The default value is "off". See alsoPYTHONPERFSUPPORT
and Python support for the Linux perf profiler.Ajouté dans la version 3.12.
-X perf_jit
enables support for the Linuxperf
profiler with DWARF support. When this option is provided, theperf
profiler will be able to report Python calls using DWARF information. This option is only available on some platforms and will do nothing if is not supported on the current system. The default value is "off". See alsoPYTHON_PERF_JIT_SUPPORT
and Python support for the Linux perf profiler.Ajouté dans la version 3.13.
-X cpu_count=n
overridesos.cpu_count()
,os.process_cpu_count()
, andmultiprocessing.cpu_count()
. n must be greater than or equal to 1. This option may be useful for users who need to limit CPU resources of a container system. See alsoPYTHON_CPU_COUNT
. If n isdefault
, nothing is overridden.Ajouté dans la version 3.13.
-X presite=package.module
specifies a module that should be imported before thesite
module is executed and before the__main__
module exists. Therefore, the imported module isn't__main__
. This can be used to execute code early during Python initialization. Python needs to be built in debug mode for this option to exist. See alsoPYTHON_PRESITE
.Ajouté dans la version 3.13.
-X gil=0,1
forces the GIL to be disabled or enabled, respectively. Setting to0
is only available in builds configured with--disable-gil
. See alsoPYTHON_GIL
and Free-threaded CPython.Ajouté dans la version 3.13.
Il est aussi possible de passer des valeurs arbitraires et de les récupérer par le dictionnaire
sys._xoptions
.Ajouté dans la version 3.2.
Modifié dans la version 3.9: Removed the
-X showalloccount
option.Modifié dans la version 3.10: Removed the
-X oldparser
option.
1.1.4. Controlling color¶
The Python interpreter is configured by default to use colors to highlight output in certain situations such as when displaying tracebacks. This behavior can be controlled by setting different environment variables.
Setting the environment variable TERM
to dumb
will disable color.
If the FORCE_COLOR
environment variable is set, then color will be
enabled regardless of the value of TERM. This is useful on CI systems which
aren’t terminals but can still display ANSI escape sequences.
If the NO_COLOR
environment variable is set, Python will disable all color
in the output. This takes precedence over FORCE_COLOR
.
All these environment variables are used also by other tools to control color
output. To control the color output only in the Python interpreter, the
PYTHON_COLORS
environment variable can be used. This variable takes
precedence over NO_COLOR
, which in turn takes precedence over
FORCE_COLOR
.
1.1.5. Options à ne pas utiliser¶
1.2. Variables d'environnement¶
Les variables d'environnement suivantes modifient le comportement de Python. Elles sont analysées avant les options de la ligne de commande, autres que -E ou -I. Il est d'usage que les options de la ligne de commande prennent le pas sur les variables d'environnement en cas de conflit.
- PYTHONHOME¶
Modifie l'emplacement des bibliothèques standards de Python. Par défaut, les bibliothèques sont recherchées dans
préfixe/lib/pythonversion
etpréfixe_exec/lib/pythonversion
oùpréfixe
etpréfixe_exec
sont des répertoires qui dépendent de l'installation (leur valeur par défaut étant/usr/local
).Quand
PYTHONHOME
est défini à un simple répertoire, sa valeur remplace à la foispréfixe
etpréfixe_exec
. Pour spécifier des valeurs différentes à ces variables, définissezPYTHONHOME
àpréfixe:préfixe_exec
.
- PYTHONPATH¶
Augmente le chemin de recherche par défaut des fichiers de modules. Le format est le même que pour
PATH
du shell : un ou plusieurs chemins de répertoires séparés paros.pathsep
(par exemple, le caractère deux-points sous Unix et point-virgule sous Windows). Les répertoires qui n'existent pas sont ignorés silencieusement.En plus des répertoires normaux, des entrées individuelles de
PYTHONPATH
peuvent faire référence à des fichiers zip contenant des modules en pur Python (soit sous forme de code source, soit sous forme compilée). Les modules d'extensions ne peuvent pas être importés à partir de fichiers zip.Le chemin de recherche par défaut dépend de l'installation mais commence généralement par
préfixe/lib/pythonversion
(voirPYTHONHOME
ci-dessus). Il est toujours ajouté àPYTHONPATH
.Comme indiqué ci-dessus dans Options de l'interface, un répertoire supplémentaire est inséré dans le chemin de recherche devant
PYTHONPATH
. Le chemin de recherche peut être manipulé depuis un programme Python avec la variablesys.path
.
- PYTHONSAFEPATH¶
Si elle est définie à une chaîne non vide, ne pas ajouter un chemin potentiellement non sûr à
sys.path
: voir l'option-P
pour les détails.Ajouté dans la version 3.11.
- PYTHONPLATLIBDIR¶
Si elle est définie à une chaîne non vide, elle remplace la valeur de
sys.platlibdir
.Ajouté dans la version 3.9.
- PYTHONSTARTUP¶
S'il s'agit d'un nom de fichier accessible en lecture, les commandes Python de ce fichier sont exécutées avant que la première invite ne soit affichée en mode interactif. Le fichier est exécuté dans le même espace de nommage que les commandes interactives, de manière à ce que les objets définis ou importés puissent être utilisés sans qualificatif dans la session interactive. Vous pouvez aussi changer les invites
sys.ps1
etsys.ps2
ainsi que le point d'entrée (hook en anglais)sys.__interactivehook__
dans ce fichier.Lève un évènement d'audit
cpython.run_startup
avec le nom du fichier en argument lorsqu'il est lancé au démarrage.
- PYTHONOPTIMIZE¶
Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option
-O
. Si elle est définie à un entier, c'est équivalent à spécifier l'option-O
plusieurs fois.
- PYTHONBREAKPOINT¶
Si elle est définie, elle fait référence à un appelable en utilisant la notation des chemins délimités par des points. Le module contenant l'appelable est importé et l'appelable est alors lancé par l'implémentation par défaut de
sys.breakpointhook()
, elle-même étant appelée par la fonction nativebreakpoint()
. Si elle n'est pas définie ou définie par une chaîne vide, elle vaut la même chose quepdb.set_trace
. La définir à la chaîne "0" entraine que l'implémentation par défaut desys.breakpointhook()
ne fait rien et s'interrompt immédiatement.Ajouté dans la version 3.7.
- PYTHONDEBUG¶
Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option
-d
. Si elle est définie à un entier, c'est équivalent à spécifier l'option-d
plusieurs fois.This environment variable requires a debug build of Python, otherwise it's ignored.
- PYTHONINSPECT¶
Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option
-i
.Cette variable peut aussi être modifiée par du code Python en utilisant
os.environ
pour forcer le mode introspectif à la fin du programme.Lève un évènement d'audit
cpython.run_stdin
sans argument.Modifié dans la version 3.12.5: (also 3.11.10, 3.10.15, 3.9.20, and 3.8.20) Emits audit events.
Modifié dans la version 3.13: Uses PyREPL if possible, in which case
PYTHONSTARTUP
is also executed. Emits audit events.
- PYTHONUNBUFFERED¶
Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option
-u
.
- PYTHONVERBOSE¶
Si elle est définie à une chaîne non vide, c'est équivalent à spécifier l'option
-v
. Si elle est définie à un entier, c'est équivalent à spécifier l'option-v
plusieurs fois.
- PYTHONCASEOK¶
Si elle est définie, Python ignore la casse dans les instructions
import
. Ceci ne fonctionne que sous Windows et macOS.
- PYTHONDONTWRITEBYTECODE¶
Si elle est définie et n'est pas une chaîne vide, Python n'écrit pas de fichier
.pyc
à l'importation des modules sources. C'est équivalent à spécifier l'option-B
.
- PYTHONPYCACHEPREFIX¶
Si elle est définie, Python n'écrit pas ses fichiers
.pyc
dans__pycache__
mais dans une arborescence miroir à ce chemin. C'est l'équivalent de l'option-X
pycache_prefix=PATH
.Ajouté dans la version 3.8.
- PYTHONHASHSEED¶
Si cette variable n'est pas définie ou définie à
random
, une valeur aléatoire est utilisée pour saler les empreintes des objetsstr
etbytes
.Si
PYTHONHASHSEED
est définie à une valeur entière, elle est utilisée comme valeur de salage pour générer les empreintes des types utilisant l'imprévisibilité du hachage.L'objectif est d'avoir des empreintes reproductibles, pour des tests de l'interpréteur lui-même ou pour qu'un groupe de processus Python puisse partager des empreintes.
Le nombre entier doit être écrit en base 10 et être compris entre 0 et 4 294 967 295. Spécifier la valeur 0 désactive l'imprévisibilité des empreintes.
Ajouté dans la version 3.2.3.
- PYTHONINTMAXSTRDIGITS¶
Si un entier est assigné à cette variable, elle est utilisée pour configurer la limite globale de l'interpréteur limitation de la longueur de conversion des chaînes de caractères entiers.
Ajouté dans la version 3.11.
- PYTHONIOENCODING¶
Si la variable est définie sous la forme
nom_encodage:gestionnaire_erreur
avant le lancement de l'interpréteur, cela prend le pas sur l'encodage utilisé pour l'entrée standard, la sortie standard ou la sortie d'erreur.nom_encodage
et:gestionnaire_erreur
sont facultatifs tous les deux et possèdent la même signification que dansstr.encode()
.Pour la sortie d'erreur, la partie
:gestionnaire_erreur
est ignorée : le gestionnaire est toujours'backslashreplace'
.Modifié dans la version 3.4: La partie
nom_encodage
est maintenant optionnelle.Modifié dans la version 3.6: Sous Windows, l'encodage spécifié par cette variable est ignoré pour le tampon des consoles interactives à moins que
PYTHONLEGACYWINDOWSSTDIO
ne soit aussi spécifié. Les fichiers et tubes (pipes en anglais) redirigés vers les flux standards ne sont pas concernés.
- PYTHONNOUSERSITE¶
Si elle est définie, Python n'ajoute pas le répertoire
site-packages propre à l'utilisateur
àsys.path
.Voir aussi
PEP 370 -- Répertoire site-packages propre à l'utilisateur
- 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
.Voir aussi
PEP 370 -- Répertoire site-packages propre à l'utilisateur
- PYTHONEXECUTABLE¶
Si cette variable d'environnement est définie,
sys.argv[0]
est définie à cette valeur au lieu de la valeur fournie par l'exécutable. Ne fonctionne que sur macOS.
- PYTHONWARNINGS¶
C'est équivalent à spécifier l'option
-W
. Si la valeur est une chaîne séparée par des virgules, c'est équivalent à spécifier l'option-W
plusieurs fois. Dans ce cas, les filtres spécifiés en derniers prennent le pas sur ceux qui les précèdent dans la liste.Les configurations les plus simples forcent l'application de l'action à tous les avertissements émis par un processus (même ceux qui auraient été ignorés par défaut) :
PYTHONWARNINGS=default # Warn once per call location PYTHONWARNINGS=error # Convert to exceptions PYTHONWARNINGS=always # Warn every time PYTHONWARNINGS=all # Same as PYTHONWARNINGS=always PYTHONWARNINGS=module # Warn once per calling module PYTHONWARNINGS=once # Warn once per Python process PYTHONWARNINGS=ignore # Never warn
Voir Le filtre des avertissements et Rédaction de filtres d'avertissement pour plus de détails.
- 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.Ajouté dans la version 3.3.
- PYTHONTRACEMALLOC¶
If this environment variable is set to a non-empty string, start tracing Python memory allocations using the
tracemalloc
module. The value of the variable is the maximum number of frames stored in a traceback of a trace. For example,PYTHONTRACEMALLOC=1
stores only the most recent frame. See thetracemalloc.start()
function for more information. This is equivalent to setting the-X
tracemalloc
option.Ajouté dans la version 3.4.
- PYTHONPROFILEIMPORTTIME¶
If this environment variable is set to a non-empty string, Python will show how long each import takes. This is equivalent to setting the
-X
importtime
option.Ajouté dans la version 3.7.
- PYTHONASYNCIODEBUG¶
Si elle est définie à une chaîne non vide, active le mode debogage du module
asyncio
.Ajouté dans la version 3.4.
- PYTHONMALLOC¶
Définit l'allocateur mémoire de Python ou installe des points d'entrée (hooks en anglais) de débogage.
Définit la famille d'allocateurs mémoire utilisés par Python :
default
: utilise les allocateurs de mémoire par défaut.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.mimalloc
: use the mimalloc allocator forPYMEM_DOMAIN_MEM
andPYMEM_DOMAIN_OBJ
domains and use themalloc()
function for thePYMEM_DOMAIN_RAW
domain.
Chacun de ces modes possède un pendant qui ajoute en plus des points d'entrée de débogage :
debug
: installe des points d'entrée de débogage au-dessus des allocateurs de mémoire par défaut.malloc_debug
: identique àmalloc
mais installe aussi des points d'entrée de débogage.pymalloc_debug
pourpymalloc
.mimalloc_debug
: same asmimalloc
but also install debug hooks.
Ajouté dans la version 3.6.
Modifié dans la version 3.7: L'allocateur
default
a été ajouté.
- PYTHONMALLOCSTATS¶
Si elle est définie à une chaîne non vide, Python affiche des statistiques relatives à l’allocateur mémoire pymalloc chaque fois qu'un objet est créé par ce gestionnaire, ainsi qu'à la fin de l'exécution du programme.
Cette variable est ignorée si la variable d'environnement
PYTHONMALLOC
est utilisée pour forcer l'allocateurmalloc()
de la bibliothèque C standard ou si Python est configuré sans le support depymalloc
.Modifié dans la version 3.6: Cette variable peut maintenant être utilisée avec Python compilé en mode release. Elle n'a pas d'effet si elle est définie à une chaine vide.
- PYTHONLEGACYWINDOWSFSENCODING¶
Si elle est définie et n’est pas une chaîne vide, l'encodage utilisé pour interagir avec le système de fichiers et le gestionnaire d'erreurs associé reviennent à leurs valeurs par défaut pré-3.6, respectivement
'mbcs'
et'replace'
. Sinon, elles prennent les nouvelles valeurs par défaut"UTF-8"
et"surrogatepass"
.This may also be enabled at runtime with
sys._enablelegacywindowsfsencoding()
.Availability: Windows.
Ajouté dans la version 3.6: Voir la PEP 529 pour plus d'informations.
- PYTHONLEGACYWINDOWSSTDIO¶
Si elle est définie et n’est pas une chaîne vide, n'utilise pas les lecteur et écrivain de la nouvelle console. Cela signifie que les caractères Unicode sont encodés avec l'encodage de la console active plutôt qu'en UTF-8.
Cette variable est ignorée si les flux standards sont redirigés (vers des fichiers ou des tubes) plutôt que pointant vers des mémoires tampons de console.
Availability: Windows.
Ajouté dans la version 3.6.
- PYTHONCOERCECLOCALE¶
Si elle est définie à la valeur
0
, l'application en ligne de commande principale Python ne prend pas en compte les configurations régionales C et POSIX à base ASCII, mais bascule sur une alternative basée sur l'UTF-8 qui doit posséder plus de possibilités.Si cette variable n'est pas définie (ou est définie à une valeur autre que
0
), que la variable d'environnement de configuration régionaleLC_ALL
est également non définie et que la configuration régionale indiquée dans la catégorieLC_TYPE
est soit la région par défautC
, soit la régionPOSIX
qui demande explicitement de l'ASCII, alors l'interpréteur en ligne de commande Python essaie de configurer les paramètres régionaux pour la catégorieLC_TYPE
dans l'ordre suivant avant de charger l'exécutable de l'interpréteur :C.UTF-8
C.utf8
UTF-8
Si la définition d'une des configurations régionales fonctionne, la variable d'environnement
LC_TYPE
est aussi définie ainsi dans l'environnement du processus avant que l'exécutable Python ne soit initialisé. Ceci assure que, en plus d'être vue par l'interpréteur lui-même et tous les autres composants prenant en charge la configuration régionale dans le même processus (telle que la bibliothèque GNUreadline
), la configuration mise à jour est aussi valable pour les sous-processus (indépendamment du fait qu'ils utilisent un interpréteur Python ou non) ainsi que pour les opérations qui font appel à l'environnement (qui utiliseraient sinon la configuration régionale C courante, tel que c'est le cas pour la propre fonction Pythonlocale.getdefaultlocale()
).La configuration d'une de ces variables régionales (soit explicitement, soit via le mécanisme décrit ci-dessus) active automatiquement
surrogateescape
pour la gestion des erreurs desys.stdin
etsys.stdout
(sys.stderr
continue d'utiliserbackslashreplace
comme pour toute autre configuration régionale). Ce comportement relatif à la gestion des flux standards peut être surchargé, comme d'habitude, parPYTHONIOENCODING
.À fin de débogage, définir
PYTHONCOERCECLOCALE=warn
indique à Python d'émettre les messages d'avertissement surstderr
si la configuration régionale est activée, ou si une configuration régionale qui aurait activé est toujours active quand l'interpréteur Python est initialisé.Notez également que même si la contrainte sur la configuration régionale est désactivée, ou si elle ne trouve pas une configuration satisfaisante et échoue,
PYTHONUTF8
s'active par défaut avec une configuration régionale par défaut à base ASCII. Ces fonctionnalités doivent être désactivées pour forcer l'interpréteur à utiliserASCII
en lieu et place deUTF-8
pour les interfaces avec le système.Availability: Unix.
Ajouté dans la version 3.7: Voir la PEP 538 pour plus d'informations.
- PYTHONDEVMODE¶
If this environment variable is set to a non-empty string, enable Python Development Mode, introducing additional runtime checks that are too expensive to be enabled by default. This is equivalent to setting the
-X
dev
option.Ajouté dans la version 3.7.
- PYTHONUTF8¶
La valeur
1
active le mode UTF-8.La valeur
0
désactive le mode UTF-8.Définir une valeur autre (non vide) entraine une erreur pendant l'initialisation de l'interpréteur.
Ajouté dans la version 3.7.
- PYTHONWARNDEFAULTENCODING¶
Si elle est définie à une chaîne non vide, un avertissement
EncodingWarning
est émis lorsque l'encodage par défaut de la configuration régionale est utilisé.Voir Opt-in EncodingWarning pour plus de détails.
Ajouté dans la version 3.10.
- PYTHONNODEBUGRANGES¶
Si cette variable est définie, cela désactive l'inclusion des tableaux qui font la correspondance avec des informations extérieures (ligne de fin, numéros des colonnes de début et de fin) pour toutes les instructions du code. C'est utile quand vous souhaitez diminuer la taille du code objet et des fichiers pyc ou alors quand vous voulez supprimer des informations de position quand l'interpréteur affiche les traces d'appels.
Ajouté dans la version 3.11.
- PYTHONPERFSUPPORT¶
If this variable is set to a nonzero value, it enables support for the Linux
perf
profiler so Python calls can be detected by it.If set to
0
, disable Linuxperf
profiler support.See also the
-X perf
command-line option and Python support for the Linux perf profiler.Ajouté dans la version 3.12.
- PYTHON_PERF_JIT_SUPPORT¶
If this variable is set to a nonzero value, it enables support for the Linux
perf
profiler so Python calls can be detected by it using DWARF information.If set to
0
, disable Linuxperf
profiler support.See also the
-X perf_jit
command-line option and Python support for the Linux perf profiler.Ajouté dans la version 3.13.
- PYTHON_CPU_COUNT¶
If this variable is set to a positive integer, it overrides the return values of
os.cpu_count()
andos.process_cpu_count()
.See also the
-X cpu_count
command-line option.Ajouté dans la version 3.13.
- PYTHON_FROZEN_MODULES¶
If this variable is set to
on
oroff
, it determines whether or not frozen modules are ignored by the import machinery. A value ofon
means they get imported andoff
means they are ignored. The default ison
for non-debug builds (the normal case) andoff
for debug builds. Note that theimportlib_bootstrap
andimportlib_bootstrap_external
frozen modules are always used, even if this flag is set tooff
.See also the
-X frozen_modules
command-line option.Ajouté dans la version 3.13.
- PYTHON_COLORS¶
If this variable is set to
1
, the interpreter will colorize various kinds of output. Setting it to0
deactivates this behavior. See also Controlling color.Ajouté dans la version 3.13.
- PYTHON_BASIC_REPL¶
If this variable is set to
1
, the interpreter will not attempt to load the Python-based REPL that requirescurses
andreadline
, and will instead use the traditional parser-based REPL.Ajouté dans la version 3.13.
- PYTHON_HISTORY¶
This environment variable can be used to set the location of a
.python_history
file (by default, it is.python_history
in the user's home directory).Ajouté dans la version 3.13.
- PYTHON_GIL¶
If this variable is set to
1
, the global interpreter lock (GIL) will be forced on. Setting it to0
forces the GIL off (needs Python configured with the--disable-gil
build option).See also the
-X gil
command-line option, which takes precedence over this variable, and Free-threaded CPython.Ajouté dans la version 3.13.
1.2.1. Variables en mode débogage¶
- PYTHONDUMPREFS¶
Si elle est définie, Python affiche (de manière brute) les objets et les compteurs de références toujours existant après la fermeture de l'interpréteur.
Needs Python configured with the
--with-trace-refs
build option.
- PYTHONDUMPREFSFILE¶
If set, Python will dump objects and reference counts still alive after shutting down the interpreter into a file under the path given as the value to this environment variable.
Needs Python configured with the
--with-trace-refs
build option.Ajouté dans la version 3.11.
- PYTHON_PRESITE¶
If this variable is set to a module, that module will be imported early in the interpreter lifecycle, before the
site
module is executed, and before the__main__
module is created. Therefore, the imported module is not treated as__main__
.This can be used to execute code early during Python initialization.
To import a submodule, use
package.module
as the value, like in an import statement.See also the
-X presite
command-line option, which takes precedence over this variable.Needs Python configured with the
--with-pydebug
build option.Ajouté dans la version 3.13.