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 de sys.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 argument command.

-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 de sys.path.

-I option can be used to run the script in isolated mode where sys.path contains neither the current directory nor the user's site-packages directory. All PYTHON* 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 argument module-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 de sys.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 where sys.path contains neither the script's directory nor the user's site-packages directory. All PYTHON* environment variables are ignored, too.

Lève un évènement d'audit cpython.run_file avec comme argument filename.

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

Lancement de l'interpréteur

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 or bytearray to str without specifying encoding or comparing bytes or bytearray with str or bytes with int. Issue an error when the option is given twice (-bb).

Modifié dans la version 3.5: Affects also comparisons of bytes with int.

-B

S'il est donné, Python ne tente pas d'écrire de fichier .pyc ou .pyo à l'importation des modules sources. Voir aussi PYTHONDONTWRITEBYTECODE.

--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 est default, les caches de fichiers de code intermédiaire sont validés en fonction de leur sémantique par défaut. Quand la valeur est always, tous les fichiers .pyc, qu'ils soient vérifiés ou non, sont validés par rapport à leurs fichiers sources correspondants. Quand la valeur est never, 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 and PYTHONHOME, that might be set.

Voir aussi les options -P et -I (mode isolé).

-i

Enter interactive mode after execution.

Using the -i option will enter interactive mode in any of the following circumstances:

  • When a script is passed as first argument

  • When the -c option is used

  • When the -m option is used

Interactive mode will start even when sys.stdin does not appear to be a terminal. The PYTHONSTARTUP file is not read.

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. All PYTHON* 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 aussi PYTHONOPTIMIZE.

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 et python (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 de sys.path qu’il implique. Désactive aussi ces manipulations si site est importé explicitement plus tard (appelez site.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 type DeprecationWarning.

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 module warnings. Par exemple, la fonction warnings.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 enable faulthandler. See also PYTHONFAULTHANDLER.

    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 the tracemalloc 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. See tracemalloc.start() and PYTHONTRACEMALLOC 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 aussi PYTHONINTMAXSTRDIGITS.

    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 est python3 -X importtime -c 'import asyncio'. Voir aussi PYTHONPROFILEIMPORTTIME.

    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 also PYTHONDEVMODE.

    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 also PYTHONUTF8.

    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 aussi PYTHONPYCACHEPREFIX.

    Ajouté dans la version 3.8.

  • -X warn_default_encoding pour émettre un EncodingWarning lorsqu'un fichier est ouvert avec l'encodage par défaut des paramètres régionaux. Voir aussi PYTHONWARNDEFAULTENCODING.

    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 aussi PYTHONNODEBUGRANGES.

    Ajouté dans la version 3.11.

  • -X frozen_modules determines whether or not frozen modules are ignored by the import machinery. A value of on means they get imported and off means they are ignored. The default is on if this is an installed Python (the normal case). If it's under development (running from the source tree) then the default is off. Note that the importlib_bootstrap and importlib_bootstrap_external frozen modules are always used, even if this flag is set to off. See also PYTHON_FROZEN_MODULES.

    Ajouté dans la version 3.11.

  • -X perf enables support for the Linux perf profiler. When this option is provided, the perf 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 also PYTHONPERFSUPPORT and Python support for the Linux perf profiler.

    Ajouté dans la version 3.12.

  • -X perf_jit enables support for the Linux perf profiler with DWARF support. When this option is provided, the perf 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 also PYTHON_PERF_JIT_SUPPORT and Python support for the Linux perf profiler.

    Ajouté dans la version 3.13.

  • -X cpu_count=n overrides os.cpu_count(), os.process_cpu_count(), and multiprocessing.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 also PYTHON_CPU_COUNT. If n is default, nothing is overridden.

    Ajouté dans la version 3.13.

  • -X presite=package.module specifies a module that should be imported before the site 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 also PYTHON_PRESITE.

    Ajouté dans la version 3.13.

  • -X gil=0,1 forces the GIL to be disabled or enabled, respectively. Setting to 0 is only available in builds configured with --disable-gil. See also PYTHON_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

-J

Utilisation réservée à Jython.

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 et préfixe_exec/lib/pythonversion où préfixe et pré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 fois préfixe et préfixe_exec. Pour spécifier des valeurs différentes à ces variables, définissez PYTHONHOME à 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 par os.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 (voir PYTHONHOME 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 variable sys.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 et sys.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 native breakpoint(). Si elle n'est pas définie ou définie par une chaîne vide, elle vaut la même chose que pdb.set_trace. La définir à la chaîne "0" entraine que l'implémentation par défaut de sys.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 objets str et bytes.

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 dans str.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 the user site-packages directory and installation paths for python -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 for SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL 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 the tracemalloc.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 :

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 pour pymalloc.

  • mimalloc_debug: same as mimalloc 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'allocateur malloc() de la bibliothèque C standard ou si Python est configuré sans le support de pymalloc.

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égionale LC_ALL est également non définie et que la configuration régionale indiquée dans la catégorie LC_TYPE est soit la région par défaut C, soit la région POSIX 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égorie LC_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 GNU readline), 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 Python locale.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 de sys.stdin et sys.stdout (sys.stderr continue d'utiliser backslashreplace comme pour toute autre configuration régionale). Ce comportement relatif à la gestion des flux standards peut être surchargé, comme d'habitude, par PYTHONIOENCODING.

À fin de débogage, définir PYTHONCOERCECLOCALE=warn indique à Python d'émettre les messages d'avertissement sur stderr 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 à utiliser ASCII en lieu et place de UTF-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 Linux perf 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 Linux perf 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() and os.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 or off, it determines whether or not frozen modules are ignored by the import machinery. A value of on means they get imported and off means they are ignored. The default is on for non-debug builds (the normal case) and off for debug builds. Note that the importlib_bootstrap and importlib_bootstrap_external frozen modules are always used, even if this flag is set to off.

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 to 0 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 requires curses and readline, 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 to 0 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.