# 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.

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.

- When called with `-c command`, it executes the Python statement(s) given as command. Here command may contain multiple statements separated by newlines.

- 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`.

  Modifié dans la version 3.14: command is automatically dedented before execution.

-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`.

  Obsolète depuis la version 3.15: Deprecate `-b` and `-bb` command line options and schedule them to become no-op in Python 3.17. These were primarily helpers for the Python 2 -> 3 transition. Starting with Python 3.17, no `BytesWarning` will be raised for these cases; use a type checker instead.

-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

  Turn on hash randomization. This option only has an effect if the `PYTHONHASHSEED` environment variable is set to anything other than `random`, since hash randomization is enabled by default.

  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 https://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.

  The message field must match the start of the warning message; this match is case-insensitive. If it starts and ends with a forward slash (`/`), it specifies a regular expression, otherwise it specifies a literal string.

  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. If it starts and ends with a forward slash (`/`), it specifies a regular expression that the start of the fully qualified module name must match, otherwise it specifies a literal string that the fully qualified module name must be equal to.

  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.

  Modifié dans la version 3.15: Added regular expression support for message and module.

-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` to show how long each import takes. It shows module name, cumulative time (including nested imports) and self time (excluding nested imports). Note that its output may be broken in multi-threaded application. Typical usage is `python -X importtime -c 'import asyncio'`.

    `-X importtime=2` enables additional output that indicates when an imported module has already been loaded. In such cases, the string `cached` will be printed in both time columns.

    See also `PYTHONPROFILEIMPORTTIME`.

    Ajouté dans la version 3.7.

    Modifié dans la version 3.14: Added `-X importtime=2` to also trace imports of loaded modules, and reserved values other than `1` and `2` for future use.

  - `-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 perf map compatible profilers.

    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 perf map compatible profilers.

    Ajouté dans la version 3.13.

  - `-X disable_remote_debug` disables the remote debugging support as described in PEP 768. This includes both the functionality to schedule code for execution in another process and the functionality to receive code for execution in the current process.

    This option is only available on some platforms and will do nothing if is not supported on the current system. See also `PYTHON_DISABLE_REMOTE_DEBUG` and PEP 768.

    Ajouté dans la version 3.14.

  - `-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=module` or `-X presite=module:func` specifies an entry point that should be executed 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`.

    Modifié dans la version 3.15: Accept also `module:func` entry point format.

    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.

  - `-X thread_inherit_context=0,1` causes `Thread` to, by default, use a copy of context of the caller of `Thread.start()` when starting. Otherwise, threads will start with an empty context. If unset, the value of this option defaults to `1` on free-threaded builds and to `0` otherwise. See also `PYTHON_THREAD_INHERIT_CONTEXT`.

    Ajouté dans la version 3.14.

  - `-X context_aware_warnings=0,1` causes the `warnings.catch_warnings` context manager to use a `ContextVar` to store warnings filter state. If unset, the value of this option defaults to `1` on free-threaded builds and to `0` otherwise. See also `PYTHON_CONTEXT_AWARE_WARNINGS`.

    Ajouté dans la version 3.14.

  - `-X pathconfig_warnings=0,1` if true (`1`) then The initialization of the sys.path module search path is allowed to log warnings into stderr. If false (`0`) suppress these warnings. Set to true by default. See also `PYTHON_PATHCONFIG_WARNINGS`.

    Ajouté dans la version 3.15.

  - `-X tlbc=0,1` enables (1, the default) or disables (0) thread-local bytecode in builds configured with `--disable-gil`. When disabled, this also disables the specializing interpreter. See also `PYTHON_TLBC`.

    Ajouté dans la version 3.14.

  - `-X lazy_imports=all,normal` controls lazy import behavior. `all` makes all imports lazy by default, and `normal` (the default) respects the `lazy` keyword in source code. See also `PYTHON_LAZY_IMPORTS`.

    Ajouté dans la version 3.15.

  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.

Supprimé dans la version 3.14: `-J` is no longer reserved for use by Jython, and now has no special meaning.

### 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.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

  This is equivalent to the `-s` option. If this is set, Python won't add the `user site-packages directory` to `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`.

  To disable the user site-packages, see `PYTHONNOUSERSITE` or the `-s` option.

  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.

  Modifié dans la version 3.15: Added regular expression support for message and module.

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 `1`, Python will show how long each import takes. If set to `2`, Python will include output for imported modules that have already been loaded. This is equivalent to setting the `-X` `importtime` option.

  Ajouté dans la version 3.7.

  Modifié dans la version 3.14: Added `PYTHONPROFILEIMPORTTIME=2` to also trace imports of loaded modules.

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 the `malloc()` function of the C library for all domains (`PYMEM_DOMAIN_RAW`, `PYMEM_DOMAIN_MEM`, `PYMEM_DOMAIN_OBJ`).

  - `pymalloc`: use the pymalloc allocator for `PYMEM_DOMAIN_MEM` and `PYMEM_DOMAIN_OBJ` domains and use the `malloc()` function for the `PYMEM_DOMAIN_RAW` domain.

  - `mimalloc`: use the mimalloc allocator for `PYMEM_DOMAIN_MEM` and `PYMEM_DOMAIN_OBJ` domains and use the `malloc()` function for the `PYMEM_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` pour `pymalloc`.

  - `mimalloc_debug`: same as `mimalloc` but also install debug hooks.

  Note

  In the free-threaded build, the `malloc`, `malloc_debug`, `pymalloc`, and `pymalloc_debug` values are not supported. Only `default`, `debug`, `mimalloc`, and `mimalloc_debug` are accepted.

  Ajouté dans la version 3.6.

  Modifié dans la version 3.7: L'allocateur `default` a été ajouté.

PYTHONMALLOCSTATS

  If set to a non-empty string, Python will print statistics of the pymalloc memory allocator or the mimalloc memory allocator (whichever is in use) every time a new object arena is created, and on shutdown.

  This variable is ignored if the `PYTHONMALLOC` environment variable is used to force the `malloc()` allocator of the C library, or if Python is configured without both `pymalloc` and `mimalloc` support.

  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.

PYTHON_PYMALLOC_HUGEPAGES

  If set to a non-zero integer, enable huge page support for pymalloc arenas. Set to `0` or unset to disable. Python must be compiled with `--with-pymalloc-hugepages` for this variable to have any effect.

  When enabled, arena allocation uses `MAP_HUGETLB` (Linux) or `MEM_LARGE_PAGES` (Windows) with automatic fallback to regular pages if huge pages are not available.

  Avertissement

  On Linux, if the huge-page pool is exhausted, page faults — including copy-on-write faults triggered by `os.fork()` — deliver `SIGBUS` and kill the process. Only enable this in environments where the huge-page pool is properly sized and fork-safety is not a concern.

  On Windows you need a special privilege. See the Windows documentation for large pages for details. Python will fail on startup if the required privilege SeLockMemoryPrivilege is not held by the user.

  Ajouté dans la version 3.15.

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"`.

  Disponibilité: 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.

  Disponibilité: 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.

  Disponibilité: 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 perf map compatible profilers.

  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 perf map compatible profilers.

  Ajouté dans la version 3.13.

PYTHON_DISABLE_REMOTE_DEBUG

  If this variable is set to a non-empty string, it disables the remote debugging feature described in PEP 768. This includes both the functionality to schedule code for execution in another process and the functionality to receive code for execution in the current process.

  See also the `-X disable_remote_debug` command-line option.

  Ajouté dans la version 3.14.

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 any value, the interpreter will not attempt to load the Python-based REPL that requires `readline`, and will instead use the traditional parser-based REPL.

  Ajouté dans la version 3.13.

PYTHON_BASIC_COMPLETER

  If this variable is set to any value, PyREPL will use `rlcompleter` to implement tab completion, instead of the default one which uses colors.

  Ajouté dans la version 3.15.

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.

PYTHON_THREAD_INHERIT_CONTEXT

  If this variable is set to `1` then `Thread` will, by default, use a copy of context of the caller of `Thread.start()` when starting. Otherwise, new threads will start with an empty context. If unset, this variable defaults to `1` on free-threaded builds and to `0` otherwise. See also `-X thread_inherit_context`.

  Ajouté dans la version 3.14.

PYTHON_CONTEXT_AWARE_WARNINGS

  If set to `1` then the `warnings.catch_warnings` context manager will use a `ContextVar` to store warnings filter state. If unset, this variable defaults to `1` on free-threaded builds and to `0` otherwise. See `-X context_aware_warnings`.

  Ajouté dans la version 3.14.

PYTHON_PATHCONFIG_WARNINGS

  If true (`1`) then The initialization of the sys.path module search path is allowed to log warnings into stderr. If false (`0`) suppress these warnings. Set to true by default. See also `-X pathconfig_warnings`.

  Ajouté dans la version 3.15.

PYTHON_JIT

  On builds where experimental just-in-time compilation is available, this variable can force the JIT to be disabled (`0`) or enabled (`1`) at interpreter startup.

  Ajouté dans la version 3.13.

PYTHON_TLBC

  If set to `1` enables thread-local bytecode. If set to `0` thread-local bytecode and the specializing interpreter are disabled. Only applies to builds configured with `--disable-gil`.

  See also the `-X tlbc` command-line option.

  Ajouté dans la version 3.14.

PYTHON_LAZY_IMPORTS

  Controls lazy import behavior. Accepts two values: `all` makes all imports lazy by default, and `normal` (the default) respects the `lazy` keyword in source code.

  See also the `-X lazy_imports` command-line option.

  Ajouté dans la version 3.15.

### 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.

  Modifié dans la version 3.15: Accept also `module:func` entry point format.

  Ajouté dans la version 3.13.