Debian Codegraph @

Doc/using/cmdline.rst

raw
1 .. highlight:: sh
2
3 .. ATTENTION: You probably should update Misc/python.man, too, if you modify
4 this file.
5
6 .. _using-on-general:
7
8 Command line and environment
9 ============================
10
11 The CPython interpreter scans the command line and the environment for various
12 settings.
13
14 .. impl-detail::
15
16 Other implementations' command line schemes may differ. See
17 :ref:`implementations` for further resources.
18
19
20 .. _using-on-cmdline:
21
22 Command line
23 ------------
24
25 When invoking Python, you may specify any of these options::
26
27 python [-bBdEhiIOPqRsSuvVWx?] [-c command | -m module-name | script | - ] [args]
28
29 The most common use case is, of course, a simple invocation of a script::
30
31 python myscript.py
32
33
34 .. _using-on-interface-options:
35
36 Interface options
37 ~~~~~~~~~~~~~~~~~
38
39 The interpreter interface resembles that of the UNIX shell, but provides some
40 additional methods of invocation:
41
42 * When called with standard input connected to a tty device, it prompts for
43 commands and executes them until an EOF (an end-of-file character, you can
44 produce that with :kbd:`Ctrl-D` on UNIX or :kbd:`Ctrl-Z, Enter` on Windows) is read.
45 For more on interactive mode, see :ref:`tut-interac`.
46 * When called with a file name argument or with a file as standard input, it
47 reads and executes a script from that file.
48 * When called with a directory name argument, it reads and executes an
49 appropriately named script from that directory.
50 * When called with ``-c command``, it executes the Python statement(s) given as
51 *command*. Here *command* may contain multiple statements separated by
52 newlines. Leading whitespace is significant in Python statements!
53 * When called with ``-m module-name``, the given module is located on the
54 Python module path and executed as a script.
55
56 In non-interactive mode, the entire input is parsed before it is executed.
57
58 An interface option terminates the list of options consumed by the interpreter,
59 all consecutive arguments will end up in :data:`sys.argv` -- note that the first
60 element, subscript zero (``sys.argv[0]``), is a string reflecting the program's
61 source.
62
63 .. option:: -c <command>
64
65 Execute the Python code in *command*. *command* can be one or more
66 statements separated by newlines, with significant leading whitespace as in
67 normal module code.
68
69 If this option is given, the first element of :data:`sys.argv` will be
70 ``"-c"`` and the current directory will be added to the start of
71 :data:`sys.path` (allowing modules in that directory to be imported as top
72 level modules).
73
74 .. audit-event:: cpython.run_command command cmdoption-c
75
76 .. versionchanged:: 3.14
77 *command* is automatically dedented before execution.
78
79 .. option:: -m <module-name>
80
81 Search :data:`sys.path` for the named module and execute its contents as
82 the :mod:`__main__` module.
83
84 Since the argument is a *module* name, you must not give a file extension
85 (``.py``). The module name should be a valid absolute Python module name, but
86 the implementation may not always enforce this (e.g. it may allow you to
87 use a name that includes a hyphen).
88
89 Package names (including namespace packages) are also permitted. When a
90 package name is supplied instead
91 of a normal module, the interpreter will execute ``<pkg>.__main__`` as
92 the main module. This behaviour is deliberately similar to the handling
93 of directories and zipfiles that are passed to the interpreter as the
94 script argument.
95
96 .. note::
97
98 This option cannot be used with built-in modules and extension modules
99 written in C, since they do not have Python module files. However, it
100 can still be used for precompiled modules, even if the original source
101 file is not available.
102
103 If this option is given, the first element of :data:`sys.argv` will be the
104 full path to the module file (while the module file is being located, the
105 first element will be set to ``"-m"``). As with the :option:`-c` option,
106 the current directory will be added to the start of :data:`sys.path`.
107
108 :option:`-I` option can be used to run the script in isolated mode where
109 :data:`sys.path` contains neither the current directory nor the user's
110 site-packages directory. All ``PYTHON*`` environment variables are
111 ignored, too.
112
113 Many standard library modules contain code that is invoked on their execution
114 as a script. An example is the :mod:`timeit` module::
115
116 python -m timeit -s "setup here" "benchmarked code here"
117 python -m timeit -h # for details
118
119 .. audit-event:: cpython.run_module module-name cmdoption-m
120
121 .. seealso::
122 :func:`runpy.run_module`
123 Equivalent functionality directly available to Python code
124
125 :pep:`338` -- Executing modules as scripts
126
127 .. versionchanged:: 3.1
128 Supply the package name to run a ``__main__`` submodule.
129
130 .. versionchanged:: 3.4
131 namespace packages are also supported
132
133 .. _cmdarg-dash:
134
135 .. describe:: -
136
137 Read commands from standard input (:data:`sys.stdin`). If standard input is
138 a terminal, :option:`-i` is implied.
139
140 If this option is given, the first element of :data:`sys.argv` will be
141 ``"-"`` and the current directory will be added to the start of
142 :data:`sys.path`.
143
144 .. audit-event:: cpython.run_stdin "" ""
145
146 .. _cmdarg-script:
147
148 .. describe:: <script>
149
150 Execute the Python code contained in *script*, which must be a filesystem
151 path (absolute or relative) referring to either a Python file, a directory
152 containing a ``__main__.py`` file, or a zipfile containing a
153 ``__main__.py`` file.
154
155 If this option is given, the first element of :data:`sys.argv` will be the
156 script name as given on the command line.
157
158 If the script name refers directly to a Python file, the directory
159 containing that file is added to the start of :data:`sys.path`, and the
160 file is executed as the :mod:`__main__` module.
161
162 If the script name refers to a directory or zipfile, the script name is
163 added to the start of :data:`sys.path` and the ``__main__.py`` file in
164 that location is executed as the :mod:`__main__` module.
165
166 :option:`-I` option can be used to run the script in isolated mode where
167 :data:`sys.path` contains neither the script's directory nor the user's
168 site-packages directory. All ``PYTHON*`` environment variables are
169 ignored, too.
170
171 .. audit-event:: cpython.run_file filename
172
173 .. seealso::
174 :func:`runpy.run_path`
175 Equivalent functionality directly available to Python code
176
177
178 If no interface option is given, :option:`-i` is implied, ``sys.argv[0]`` is
179 an empty string (``""``) and the current directory will be added to the
180 start of :data:`sys.path`. Also, tab-completion and history editing is
181 automatically enabled, if available on your platform (see
182 :ref:`rlcompleter-config`).
183
184 .. seealso:: :ref:`tut-invoking`
185
186 .. versionchanged:: 3.4
187 Automatic enabling of tab-completion and history editing.
188
189
190 .. _using-on-generic-options:
191
192 Generic options
193 ~~~~~~~~~~~~~~~
194
195 .. option:: -?
196 -h
197 --help
198
199 Print a short description of all command line options and corresponding
200 environment variables and exit.
201
202 .. option:: --help-env
203
204 Print a short description of Python-specific environment variables
205 and exit.
206
207 .. versionadded:: 3.11
208
209 .. option:: --help-xoptions
210
211 Print a description of implementation-specific :option:`-X` options
212 and exit.
213
214 .. versionadded:: 3.11
215
216 .. option:: --help-all
217
218 Print complete usage information and exit.
219
220 .. versionadded:: 3.11
221
222 .. option:: -V
223 --version
224
225 Print the Python version number and exit. Example output could be:
226
227 .. code-block:: none
228
229 Python 3.8.0b2+
230
231 When given twice, print more information about the build, like:
232
233 .. code-block:: none
234
235 Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00)
236 [GCC 6.2.0 20161005]
237
238 .. versionadded:: 3.6
239 The ``-VV`` option.
240
241
242 .. _using-on-misc-options:
243
244 Miscellaneous options
245 ~~~~~~~~~~~~~~~~~~~~~
246
247 .. option:: -b
248
249 Issue a warning when converting :class:`bytes` or :class:`bytearray` to
250 :class:`str` without specifying encoding or comparing :class:`!bytes` or
251 :class:`!bytearray` with :class:`!str` or :class:`!bytes` with :class:`int`.
252 Issue an error when the option is given twice (:option:`!-bb`).
253
254 .. versionchanged:: 3.5
255 Affects also comparisons of :class:`bytes` with :class:`int`.
256
257 .. option:: -B
258
259 If given, Python won't try to write ``.pyc`` files on the
260 import of source modules. See also :envvar:`PYTHONDONTWRITEBYTECODE`.
261
262
263 .. option:: --check-hash-based-pycs default|always|never
264
265 Control the validation behavior of hash-based ``.pyc`` files. See
266 :ref:`pyc-invalidation`. When set to ``default``, checked and unchecked
267 hash-based bytecode cache files are validated according to their default
268 semantics. When set to ``always``, all hash-based ``.pyc`` files, whether
269 checked or unchecked, are validated against their corresponding source
270 file. When set to ``never``, hash-based ``.pyc`` files are not validated
271 against their corresponding source files.
272
273 The semantics of timestamp-based ``.pyc`` files are unaffected by this
274 option.
275
276
277 .. option:: -d
278
279 Turn on parser debugging output (for expert only).
280 See also the :envvar:`PYTHONDEBUG` environment variable.
281
282 This option requires a :ref:`debug build of Python <debug-build>`, otherwise
283 it's ignored.
284
285
286 .. option:: -E
287
288 Ignore all ``PYTHON*`` environment variables, e.g.
289 :envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
290
291 See also the :option:`-P` and :option:`-I` (isolated) options.
292
293
294 .. option:: -i
295
296 Enter interactive mode after execution.
297
298 Using the :option:`-i` option will enter interactive mode in any of the following circumstances\:
299
300 * When a script is passed as first argument
301 * When the :option:`-c` option is used
302 * When the :option:`-m` option is used
303
304 Interactive mode will start even when :data:`sys.stdin` does not appear to be a terminal. The
305 :envvar:`PYTHONSTARTUP` file is not read.
306
307 This can be useful to inspect global variables or a stack trace when a script
308 raises an exception. See also :envvar:`PYTHONINSPECT`.
309
310
311 .. option:: -I
312
313 Run Python in isolated mode. This also implies :option:`-E`, :option:`-P`
314 and :option:`-s` options.
315
316 In isolated mode :data:`sys.path` contains neither the script's directory nor
317 the user's site-packages directory. All ``PYTHON*`` environment
318 variables are ignored, too. Further restrictions may be imposed to prevent
319 the user from injecting malicious code.
320
321 .. versionadded:: 3.4
322
323
324 .. option:: -O
325
326 Remove assert statements and any code conditional on the value of
327 :const:`__debug__`. Augment the filename for compiled
328 (:term:`bytecode`) files by adding ``.opt-1`` before the ``.pyc``
329 extension (see :pep:`488`). See also :envvar:`PYTHONOPTIMIZE`.
330
331 .. versionchanged:: 3.5
332 Modify ``.pyc`` filenames according to :pep:`488`.
333
334
335 .. option:: -OO
336
337 Do :option:`-O` and also discard docstrings. Augment the filename
338 for compiled (:term:`bytecode`) files by adding ``.opt-2`` before the
339 ``.pyc`` extension (see :pep:`488`).
340
341 .. versionchanged:: 3.5
342 Modify ``.pyc`` filenames according to :pep:`488`.
343
344
345 .. option:: -P
346
347 Don't prepend a potentially unsafe path to :data:`sys.path`:
348
349 * ``python -m module`` command line: Don't prepend the current working
350 directory.
351 * ``python script.py`` command line: Don't prepend the script's directory.
352 If it's a symbolic link, resolve symbolic links.
353 * ``python -c code`` and ``python`` (REPL) command lines: Don't prepend an
354 empty string, which means the current working directory.
355
356 See also the :envvar:`PYTHONSAFEPATH` environment variable, and :option:`-E`
357 and :option:`-I` (isolated) options.
358
359 .. versionadded:: 3.11
360
361
362 .. option:: -q
363
364 Don't display the copyright and version messages even in interactive mode.
365
366 .. versionadded:: 3.2
367
368
369 .. option:: -R
370
371 Turn on hash randomization. This option only has an effect if the
372 :envvar:`PYTHONHASHSEED` environment variable is set to anything other
373 than ``random``, since hash randomization is enabled by default.
374
375 On previous versions of Python, this option turns on hash randomization,
376 so that the :meth:`~object.__hash__` values of str and bytes objects
377 are "salted" with an unpredictable random value. Although they remain
378 constant within an individual Python process, they are not predictable
379 between repeated invocations of Python.
380
381 Hash randomization is intended to provide protection against a
382 denial-of-service caused by carefully chosen inputs that exploit the worst
383 case performance of a dict construction, *O*\ (*n*\ :sup:`2`) complexity. See
384 https://ocert.org/advisories/ocert-2011-003.html for details.
385
386 :envvar:`PYTHONHASHSEED` allows you to set a fixed value for the hash
387 seed secret.
388
389 .. versionadded:: 3.2.3
390
391 .. versionchanged:: 3.7
392 The option is no longer ignored.
393
394
395 .. option:: -s
396
397 Don't add the :data:`user site-packages directory <site.USER_SITE>` to
398 :data:`sys.path`.
399
400 See also :envvar:`PYTHONNOUSERSITE`.
401
402 .. seealso::
403
404 :pep:`370` -- Per user site-packages directory
405
406
407 .. option:: -S
408
409 Disable the import of the module :mod:`site` and the site-dependent
410 manipulations of :data:`sys.path` that it entails. Also disable these
411 manipulations if :mod:`site` is explicitly imported later (call
412 :func:`site.main` if you want them to be triggered).
413
414
415 .. option:: -u
416
417 Force the stdout and stderr streams to be unbuffered. This option has no
418 effect on the stdin stream.
419
420 See also :envvar:`PYTHONUNBUFFERED`.
421
422 .. versionchanged:: 3.7
423 The text layer of the stdout and stderr streams now is unbuffered.
424
425
426 .. option:: -v
427
428 Print a message each time a module is initialized, showing the place
429 (filename or built-in module) from which it is loaded. When given twice
430 (:option:`!-vv`), print a message for each file that is checked for when
431 searching for a module. Also provides information on module cleanup at exit.
432
433 .. versionchanged:: 3.10
434 The :mod:`site` module reports the site-specific paths
435 and :file:`.pth` files being processed.
436
437 See also :envvar:`PYTHONVERBOSE`.
438
439
440 .. _using-on-warnings:
441 .. option:: -W arg
442
443 Warning control. Python's warning machinery by default prints warning
444 messages to :data:`sys.stderr`.
445
446 The simplest settings apply a particular action unconditionally to all
447 warnings emitted by a process (even those that are otherwise ignored by
448 default)::
449
450 -Wdefault # Warn once per call location
451 -Werror # Convert to exceptions
452 -Walways # Warn every time
453 -Wall # Same as -Walways
454 -Wmodule # Warn once per calling module
455 -Wonce # Warn once per Python process
456 -Wignore # Never warn
457
458 The action names can be abbreviated as desired and the interpreter will
459 resolve them to the appropriate action name. For example, ``-Wi`` is the
460 same as ``-Wignore``.
461
462 The full form of argument is::
463
464 action:message:category:module:lineno
465
466 Empty fields match all values; trailing empty fields may be omitted. For
467 example ``-W ignore::DeprecationWarning`` ignores all DeprecationWarning
468 warnings.
469
470 The *action* field is as explained above but only applies to warnings that
471 match the remaining fields.
472
473 The *message* field must match the whole warning message; this match is
474 case-insensitive.
475
476 The *category* field matches the warning category
477 (ex: ``DeprecationWarning``). This must be a class name; the match test
478 whether the actual warning category of the message is a subclass of the
479 specified warning category.
480
481 The *module* field matches the (fully qualified) module name; this match is
482 case-sensitive.
483
484 The *lineno* field matches the line number, where zero matches all line
485 numbers and is thus equivalent to an omitted line number.
486
487 Multiple :option:`-W` options can be given; when a warning matches more than
488 one option, the action for the last matching option is performed. Invalid
489 :option:`-W` options are ignored (though, a warning message is printed about
490 invalid options when the first warning is issued).
491
492 Warnings can also be controlled using the :envvar:`PYTHONWARNINGS`
493 environment variable and from within a Python program using the
494 :mod:`warnings` module. For example, the :func:`warnings.filterwarnings`
495 function can be used to use a regular expression on the warning message.
496
497 See :ref:`warning-filter` and :ref:`describing-warning-filters` for more
498 details.
499
500
501 .. option:: -x
502
503 Skip the first line of the source, allowing use of non-Unix forms of
504 ``#!cmd``. This is intended for a DOS specific hack only.
505
506
507 .. option:: -X
508
509 Reserved for various implementation-specific options. CPython currently
510 defines the following possible values:
511
512 * ``-X faulthandler`` to enable :mod:`faulthandler`.
513 See also :envvar:`PYTHONFAULTHANDLER`.
514
515 .. versionadded:: 3.3
516
517 * ``-X showrefcount`` to output the total reference count and number of used
518 memory blocks when the program finishes or after each statement in the
519 interactive interpreter. This only works on :ref:`debug builds
520 <debug-build>`.
521
522 .. versionadded:: 3.4
523
524 * ``-X tracemalloc`` to start tracing Python memory allocations using the
525 :mod:`tracemalloc` module. By default, only the most recent frame is
526 stored in a traceback of a trace. Use ``-X tracemalloc=NFRAME`` to start
527 tracing with a traceback limit of *NFRAME* frames.
528 See :func:`tracemalloc.start` and :envvar:`PYTHONTRACEMALLOC`
529 for more information.
530
531 .. versionadded:: 3.4
532
533 * ``-X int_max_str_digits`` configures the :ref:`integer string conversion
534 length limitation <int_max_str_digits>`. See also
535 :envvar:`PYTHONINTMAXSTRDIGITS`.
536
537 .. versionadded:: 3.11
538
539 * ``-X importtime`` to show how long each import takes. It shows module
540 name, cumulative time (including nested imports) and self time (excluding
541 nested imports). Note that its output may be broken in multi-threaded
542 application. Typical usage is ``python -X importtime -c 'import asyncio'``.
543
544 ``-X importtime=2`` enables additional output that indicates when an
545 imported module has already been loaded. In such cases, the string
546 ``cached`` will be printed in both time columns.
547
548 See also :envvar:`PYTHONPROFILEIMPORTTIME`.
549
550 .. versionadded:: 3.7
551
552 .. versionchanged:: 3.14
553
554 Added ``-X importtime=2`` to also trace imports of loaded modules,
555 and reserved values other than ``1`` and ``2`` for future use.
556
557 * ``-X dev``: enable :ref:`Python Development Mode <devmode>`, introducing
558 additional runtime checks that are too expensive to be enabled by
559 default. See also :envvar:`PYTHONDEVMODE`.
560
561 .. versionadded:: 3.7
562
563 * ``-X utf8`` enables the :ref:`Python UTF-8 Mode <utf8-mode>`.
564 ``-X utf8=0`` explicitly disables :ref:`Python UTF-8 Mode <utf8-mode>`
565 (even when it would otherwise activate automatically).
566 See also :envvar:`PYTHONUTF8`.
567
568 .. versionadded:: 3.7
569
570 * ``-X pycache_prefix=PATH`` enables writing ``.pyc`` files to a parallel
571 tree rooted at the given directory instead of to the code tree. See also
572 :envvar:`PYTHONPYCACHEPREFIX`.
573
574 .. versionadded:: 3.8
575
576 * ``-X warn_default_encoding`` issues a :class:`EncodingWarning` when the
577 locale-specific default encoding is used for opening files.
578 See also :envvar:`PYTHONWARNDEFAULTENCODING`.
579
580 .. versionadded:: 3.10
581
582 * ``-X no_debug_ranges`` disables the inclusion of the tables mapping extra
583 location information (end line, start column offset and end column offset)
584 to every instruction in code objects. This is useful when smaller code
585 objects and pyc files are desired as well as suppressing the extra visual
586 location indicators when the interpreter displays tracebacks. See also
587 :envvar:`PYTHONNODEBUGRANGES`.
588
589 .. versionadded:: 3.11
590
591 * ``-X frozen_modules`` determines whether or not frozen modules are
592 ignored by the import machinery. A value of ``on`` means they get
593 imported and ``off`` means they are ignored. The default is ``on``
594 if this is an installed Python (the normal case). If it's under
595 development (running from the source tree) then the default is ``off``.
596 Note that the :mod:`!importlib_bootstrap` and
597 :mod:`!importlib_bootstrap_external` frozen modules are always used, even
598 if this flag is set to ``off``. See also :envvar:`PYTHON_FROZEN_MODULES`.
599
600 .. versionadded:: 3.11
601
602 * ``-X perf`` enables support for the Linux ``perf`` profiler.
603 When this option is provided, the ``perf`` profiler will be able to
604 report Python calls. This option is only available on some platforms and
605 will do nothing if is not supported on the current system. The default value
606 is "off". See also :envvar:`PYTHONPERFSUPPORT` and :ref:`perf_profiling`.
607
608 .. versionadded:: 3.12
609
610 * ``-X perf_jit`` enables support for the Linux ``perf`` profiler with DWARF
611 support. When this option is provided, the ``perf`` profiler will be able
612 to report Python calls using DWARF information. This option is only available on
613 some platforms and will do nothing if is not supported on the current
614 system. The default value is "off". See also :envvar:`PYTHON_PERF_JIT_SUPPORT`
615 and :ref:`perf_profiling`.
616
617 .. versionadded:: 3.13
618
619 * ``-X disable_remote_debug`` disables the remote debugging support as described
620 in :pep:`768`. This includes both the functionality to schedule code for
621 execution in another process and the functionality to receive code for
622 execution in the current process.
623
624 This option is only available on some platforms and will do nothing
625 if is not supported on the current system. See also
626 :envvar:`PYTHON_DISABLE_REMOTE_DEBUG` and :pep:`768`.
627
628 .. versionadded:: 3.14
629
630 * :samp:`-X cpu_count={n}` overrides :func:`os.cpu_count`,
631 :func:`os.process_cpu_count`, and :func:`multiprocessing.cpu_count`.
632 *n* must be greater than or equal to 1.
633 This option may be useful for users who need to limit CPU resources of a
634 container system. See also :envvar:`PYTHON_CPU_COUNT`.
635 If *n* is ``default``, nothing is overridden.
636
637 .. versionadded:: 3.13
638
639 * :samp:`-X presite={package.module}` specifies a module that should be
640 imported before the :mod:`site` module is executed and before the
641 :mod:`__main__` module exists. Therefore, the imported module isn't
642 :mod:`__main__`. This can be used to execute code early during Python
643 initialization. Python needs to be :ref:`built in debug mode <debug-build>`
644 for this option to exist. See also :envvar:`PYTHON_PRESITE`.
645
646 .. versionadded:: 3.13
647
648 * :samp:`-X gil={0,1}` forces the GIL to be disabled or enabled,
649 respectively. Setting to ``0`` is only available in builds configured with
650 :option:`--disable-gil`. See also :envvar:`PYTHON_GIL` and
651 :ref:`whatsnew313-free-threaded-cpython`.
652
653 .. versionadded:: 3.13
654
655 * :samp:`-X thread_inherit_context={0,1}` causes :class:`~threading.Thread`
656 to, by default, use a copy of context of the caller of
657 ``Thread.start()`` when starting. Otherwise, threads will start
658 with an empty context. If unset, the value of this option defaults
659 to ``1`` on free-threaded builds and to ``0`` otherwise. See also
660 :envvar:`PYTHON_THREAD_INHERIT_CONTEXT`.
661
662 .. versionadded:: 3.14
663
664 * :samp:`-X context_aware_warnings={0,1}` causes the
665 :class:`warnings.catch_warnings` context manager to use a
666 :class:`~contextvars.ContextVar` to store warnings filter state. If
667 unset, the value of this option defaults to ``1`` on free-threaded builds
668 and to ``0`` otherwise. See also :envvar:`PYTHON_CONTEXT_AWARE_WARNINGS`.
669
670 .. versionadded:: 3.14
671
672 * :samp:`-X tlbc={0,1}` enables (1, the default) or disables (0) thread-local
673 bytecode in builds configured with :option:`--disable-gil`. When disabled,
674 this also disables the specializing interpreter. See also
675 :envvar:`PYTHON_TLBC`.
676
677 .. versionadded:: 3.14
678
679 It also allows passing arbitrary values and retrieving them through the
680 :data:`sys._xoptions` dictionary.
681
682 .. versionadded:: 3.2
683
684 .. versionchanged:: 3.9
685 Removed the ``-X showalloccount`` option.
686
687 .. versionchanged:: 3.10
688 Removed the ``-X oldparser`` option.
689
690 .. versionremoved:: 3.14
691
692 :option:`!-J` is no longer reserved for use by Jython_,
693 and now has no special meaning.
694
695 .. _Jython: https://www.jython.org/
696
697 .. _using-on-controlling-color:
698
699 Controlling color
700 ~~~~~~~~~~~~~~~~~
701
702 The Python interpreter is configured by default to use colors to highlight
703 output in certain situations such as when displaying tracebacks. This
704 behavior can be controlled by setting different environment variables.
705
706 Setting the environment variable ``TERM`` to ``dumb`` will disable color.
707
708 If the |FORCE_COLOR|_ environment variable is set, then color will be
709 enabled regardless of the value of TERM. This is useful on CI systems which
710 aren’t terminals but can still display ANSI escape sequences.
711
712 If the |NO_COLOR|_ environment variable is set, Python will disable all color
713 in the output. This takes precedence over ``FORCE_COLOR``.
714
715 All these environment variables are used also by other tools to control color
716 output. To control the color output only in the Python interpreter, the
717 :envvar:`PYTHON_COLORS` environment variable can be used. This variable takes
718 precedence over ``NO_COLOR``, which in turn takes precedence over
719 ``FORCE_COLOR``.
720
721
722 .. _using-on-envvars:
723
724 Environment variables
725 ---------------------
726
727 These environment variables influence Python's behavior, they are processed
728 before the command-line switches other than -E or -I. It is customary that
729 command-line switches override environmental variables where there is a
730 conflict.
731
732 .. envvar:: PYTHONHOME
733
734 Change the location of the standard Python libraries. By default, the
735 libraries are searched in :file:`{prefix}/lib/python{version}` and
736 :file:`{exec_prefix}/lib/python{version}`, where :file:`{prefix}` and
737 :file:`{exec_prefix}` are installation-dependent directories, both defaulting
738 to :file:`/usr/local`.
739
740 When :envvar:`PYTHONHOME` is set to a single directory, its value replaces
741 both :file:`{prefix}` and :file:`{exec_prefix}`. To specify different values
742 for these, set :envvar:`PYTHONHOME` to :file:`{prefix}:{exec_prefix}`.
743
744
745 .. envvar:: PYTHONPATH
746
747 Augment the default search path for module files. The format is the same as
748 the shell's :envvar:`PATH`: one or more directory pathnames separated by
749 :data:`os.pathsep` (e.g. colons on Unix or semicolons on Windows).
750 Non-existent directories are silently ignored.
751
752 In addition to normal directories, individual :envvar:`PYTHONPATH` entries
753 may refer to zipfiles containing pure Python modules (in either source or
754 compiled form). Extension modules cannot be imported from zipfiles.
755
756 The default search path is installation dependent, but generally begins with
757 :file:`{prefix}/lib/python{version}` (see :envvar:`PYTHONHOME` above). It
758 is *always* appended to :envvar:`PYTHONPATH`.
759
760 An additional directory will be inserted in the search path in front of
761 :envvar:`PYTHONPATH` as described above under
762 :ref:`using-on-interface-options`. The search path can be manipulated from
763 within a Python program as the variable :data:`sys.path`.
764
765
766 .. envvar:: PYTHONSAFEPATH
767
768 If this is set to a non-empty string, don't prepend a potentially unsafe
769 path to :data:`sys.path`: see the :option:`-P` option for details.
770
771 .. versionadded:: 3.11
772
773
774 .. envvar:: PYTHONPLATLIBDIR
775
776 If this is set to a non-empty string, it overrides the :data:`sys.platlibdir`
777 value.
778
779 .. versionadded:: 3.9
780
781
782 .. envvar:: PYTHONSTARTUP
783
784 If this is the name of a readable file, the Python commands in that file are
785 executed before the first prompt is displayed in interactive mode. The file
786 is executed in the same namespace where interactive commands are executed so
787 that objects defined or imported in it can be used without qualification in
788 the interactive session. You can also change the prompts :data:`sys.ps1` and
789 :data:`sys.ps2` and the hook :data:`sys.__interactivehook__` in this file.
790
791 .. audit-event:: cpython.run_startup filename envvar-PYTHONSTARTUP
792
793 Raises an :ref:`auditing event <auditing>` ``cpython.run_startup`` with
794 the filename as the argument when called on startup.
795
796
797 .. envvar:: PYTHONOPTIMIZE
798
799 If this is set to a non-empty string it is equivalent to specifying the
800 :option:`-O` option. If set to an integer, it is equivalent to specifying
801 :option:`-O` multiple times.
802
803
804 .. envvar:: PYTHONBREAKPOINT
805
806 If this is set, it names a callable using dotted-path notation. The module
807 containing the callable will be imported and then the callable will be run
808 by the default implementation of :func:`sys.breakpointhook` which itself is
809 called by built-in :func:`breakpoint`. If not set, or set to the empty
810 string, it is equivalent to the value "pdb.set_trace". Setting this to the
811 string "0" causes the default implementation of :func:`sys.breakpointhook`
812 to do nothing but return immediately.
813
814 .. versionadded:: 3.7
815
816 .. envvar:: PYTHONDEBUG
817
818 If this is set to a non-empty string it is equivalent to specifying the
819 :option:`-d` option. If set to an integer, it is equivalent to specifying
820 :option:`-d` multiple times.
821
822 This environment variable requires a :ref:`debug build of Python
823 <debug-build>`, otherwise it's ignored.
824
825
826 .. envvar:: PYTHONINSPECT
827
828 If this is set to a non-empty string it is equivalent to specifying the
829 :option:`-i` option.
830
831 This variable can also be modified by Python code using :data:`os.environ`
832 to force inspect mode on program termination.
833
834 .. audit-event:: cpython.run_stdin "" ""
835
836 .. versionchanged:: 3.12.5 (also 3.11.10, 3.10.15, 3.9.20, and 3.8.20)
837 Emits audit events.
838
839 .. versionchanged:: 3.13
840 Uses PyREPL if possible, in which case :envvar:`PYTHONSTARTUP` is
841 also executed. Emits audit events.
842
843
844 .. envvar:: PYTHONUNBUFFERED
845
846 If this is set to a non-empty string it is equivalent to specifying the
847 :option:`-u` option.
848
849
850 .. envvar:: PYTHONVERBOSE
851
852 If this is set to a non-empty string it is equivalent to specifying the
853 :option:`-v` option. If set to an integer, it is equivalent to specifying
854 :option:`-v` multiple times.
855
856
857 .. envvar:: PYTHONCASEOK
858
859 If this is set, Python ignores case in :keyword:`import` statements. This
860 only works on Windows and macOS.
861
862
863 .. envvar:: PYTHONDONTWRITEBYTECODE
864
865 If this is set to a non-empty string, Python won't try to write ``.pyc``
866 files on the import of source modules. This is equivalent to
867 specifying the :option:`-B` option.
868
869
870 .. envvar:: PYTHONPYCACHEPREFIX
871
872 If this is set, Python will write ``.pyc`` files in a mirror directory tree
873 at this path, instead of in ``__pycache__`` directories within the source
874 tree. This is equivalent to specifying the :option:`-X`
875 ``pycache_prefix=PATH`` option.
876
877 .. versionadded:: 3.8
878
879
880 .. envvar:: PYTHONHASHSEED
881
882 If this variable is not set or set to ``random``, a random value is used
883 to seed the hashes of str and bytes objects.
884
885 If :envvar:`PYTHONHASHSEED` is set to an integer value, it is used as a fixed
886 seed for generating the hash() of the types covered by the hash
887 randomization.
888
889 Its purpose is to allow repeatable hashing, such as for selftests for the
890 interpreter itself, or to allow a cluster of python processes to share hash
891 values.
892
893 The integer must be a decimal number in the range [0,4294967295]. Specifying
894 the value 0 will disable hash randomization.
895
896 .. versionadded:: 3.2.3
897
898 .. envvar:: PYTHONINTMAXSTRDIGITS
899
900 If this variable is set to an integer, it is used to configure the
901 interpreter's global :ref:`integer string conversion length limitation
902 <int_max_str_digits>`.
903
904 .. versionadded:: 3.11
905
906 .. envvar:: PYTHONIOENCODING
907
908 If this is set before running the interpreter, it overrides the encoding used
909 for stdin/stdout/stderr, in the syntax ``encodingname:errorhandler``. Both
910 the ``encodingname`` and the ``:errorhandler`` parts are optional and have
911 the same meaning as in :func:`str.encode`.
912
913 For stderr, the ``:errorhandler`` part is ignored; the handler will always be
914 ``'backslashreplace'``.
915
916 .. versionchanged:: 3.4
917 The ``encodingname`` part is now optional.
918
919 .. versionchanged:: 3.6
920 On Windows, the encoding specified by this variable is ignored for interactive
921 console buffers unless :envvar:`PYTHONLEGACYWINDOWSSTDIO` is also specified.
922 Files and pipes redirected through the standard streams are not affected.
923
924 .. envvar:: PYTHONNOUSERSITE
925
926 If this is set, Python won't add the :data:`user site-packages directory
927 <site.USER_SITE>` to :data:`sys.path`.
928
929 .. seealso::
930
931 :pep:`370` -- Per user site-packages directory
932
933
934 .. envvar:: PYTHONUSERBASE
935
936 Defines the :data:`user base directory <site.USER_BASE>`, which is used to
937 compute the path of the :data:`user site-packages directory <site.USER_SITE>`
938 and :ref:`installation paths <sysconfig-user-scheme>` for
939 ``python -m pip install --user``.
940
941 .. seealso::
942
943 :pep:`370` -- Per user site-packages directory
944
945
946 .. envvar:: PYTHONEXECUTABLE
947
948 If this environment variable is set, ``sys.argv[0]`` will be set to its
949 value instead of the value got through the C runtime. Only works on
950 macOS.
951
952 .. envvar:: PYTHONWARNINGS
953
954 This is equivalent to the :option:`-W` option. If set to a comma
955 separated string, it is equivalent to specifying :option:`-W` multiple
956 times, with filters later in the list taking precedence over those earlier
957 in the list.
958
959 The simplest settings apply a particular action unconditionally to all
960 warnings emitted by a process (even those that are otherwise ignored by
961 default)::
962
963 PYTHONWARNINGS=default # Warn once per call location
964 PYTHONWARNINGS=error # Convert to exceptions
965 PYTHONWARNINGS=always # Warn every time
966 PYTHONWARNINGS=all # Same as PYTHONWARNINGS=always
967 PYTHONWARNINGS=module # Warn once per calling module
968 PYTHONWARNINGS=once # Warn once per Python process
969 PYTHONWARNINGS=ignore # Never warn
970
971 See :ref:`warning-filter` and :ref:`describing-warning-filters` for more
972 details.
973
974
975 .. envvar:: PYTHONFAULTHANDLER
976
977 If this environment variable is set to a non-empty string,
978 :func:`faulthandler.enable` is called at startup: install a handler for
979 :const:`~signal.SIGSEGV`, :const:`~signal.SIGFPE`,
980 :const:`~signal.SIGABRT`, :const:`~signal.SIGBUS` and
981 :const:`~signal.SIGILL` signals to dump the Python traceback.
982 This is equivalent to :option:`-X` ``faulthandler`` option.
983
984 .. versionadded:: 3.3
985
986
987 .. envvar:: PYTHONTRACEMALLOC
988
989 If this environment variable is set to a non-empty string, start tracing
990 Python memory allocations using the :mod:`tracemalloc` module. The value of
991 the variable is the maximum number of frames stored in a traceback of a
992 trace. For example, ``PYTHONTRACEMALLOC=1`` stores only the most recent
993 frame.
994 See the :func:`tracemalloc.start` function for more information.
995 This is equivalent to setting the :option:`-X` ``tracemalloc`` option.
996
997 .. versionadded:: 3.4
998
999
1000 .. envvar:: PYTHONPROFILEIMPORTTIME
1001
1002 If this environment variable is set to ``1``, Python will show
1003 how long each import takes. If set to ``2``, Python will include output for
1004 imported modules that have already been loaded.
1005 This is equivalent to setting the :option:`-X` ``importtime`` option.
1006
1007 .. versionadded:: 3.7
1008
1009 .. versionchanged:: 3.14
1010
1011 Added ``PYTHONPROFILEIMPORTTIME=2`` to also trace imports of loaded modules.
1012
1013
1014 .. envvar:: PYTHONASYNCIODEBUG
1015
1016 If this environment variable is set to a non-empty string, enable the
1017 :ref:`debug mode <asyncio-debug-mode>` of the :mod:`asyncio` module.
1018
1019 .. versionadded:: 3.4
1020
1021
1022 .. envvar:: PYTHONMALLOC
1023
1024 Set the Python memory allocators and/or install debug hooks.
1025
1026 Set the family of memory allocators used by Python:
1027
1028 * ``default``: use the :ref:`default memory allocators
1029 <default-memory-allocators>`.
1030 * ``malloc``: use the :c:func:`malloc` function of the C library
1031 for all domains (:c:macro:`PYMEM_DOMAIN_RAW`, :c:macro:`PYMEM_DOMAIN_MEM`,
1032 :c:macro:`PYMEM_DOMAIN_OBJ`).
1033 * ``pymalloc``: use the :ref:`pymalloc allocator <pymalloc>` for
1034 :c:macro:`PYMEM_DOMAIN_MEM` and :c:macro:`PYMEM_DOMAIN_OBJ` domains and use
1035 the :c:func:`malloc` function for the :c:macro:`PYMEM_DOMAIN_RAW` domain.
1036 * ``mimalloc``: use the :ref:`mimalloc allocator <mimalloc>` for
1037 :c:macro:`PYMEM_DOMAIN_MEM` and :c:macro:`PYMEM_DOMAIN_OBJ` domains and use
1038 the :c:func:`malloc` function for the :c:macro:`PYMEM_DOMAIN_RAW` domain.
1039
1040 Install :ref:`debug hooks <pymem-debug-hooks>`:
1041
1042 * ``debug``: install debug hooks on top of the :ref:`default memory
1043 allocators <default-memory-allocators>`.
1044 * ``malloc_debug``: same as ``malloc`` but also install debug hooks.
1045 * ``pymalloc_debug``: same as ``pymalloc`` but also install debug hooks.
1046 * ``mimalloc_debug``: same as ``mimalloc`` but also install debug hooks.
1047
1048 .. note::
1049
1050 In the :term:`free-threaded <free threading>` build, the ``malloc``,
1051 ``malloc_debug``, ``pymalloc``, and ``pymalloc_debug`` values are not
1052 supported. Only ``default``, ``debug``, ``mimalloc``, and
1053 ``mimalloc_debug`` are accepted.
1054
1055 .. versionadded:: 3.6
1056
1057 .. versionchanged:: 3.7
1058 Added the ``"default"`` allocator.
1059
1060
1061 .. envvar:: PYTHONMALLOCSTATS
1062
1063 If set to a non-empty string, Python will print statistics of the
1064 :ref:`pymalloc memory allocator <pymalloc>` or the
1065 :ref:`mimalloc memory allocator <mimalloc>` (whichever is in use)
1066 every time a new object arena is created, and on shutdown.
1067
1068 This variable is ignored if the :envvar:`PYTHONMALLOC` environment variable
1069 is used to force the :c:func:`malloc` allocator of the C library, or if
1070 Python is configured without both ``pymalloc`` and ``mimalloc`` support.
1071
1072 .. versionchanged:: 3.6
1073 This variable can now also be used on Python compiled in release mode.
1074 It now has no effect if set to an empty string.
1075
1076
1077 .. envvar:: PYTHONLEGACYWINDOWSFSENCODING
1078
1079 If set to a non-empty string, the default :term:`filesystem encoding and
1080 error handler` mode will revert to their pre-3.6 values of 'mbcs' and
1081 'replace', respectively. Otherwise, the new defaults 'utf-8' and
1082 'surrogatepass' are used.
1083
1084 This may also be enabled at runtime with
1085 :func:`sys._enablelegacywindowsfsencoding`.
1086
1087 .. availability:: Windows.
1088
1089 .. versionadded:: 3.6
1090 See :pep:`529` for more details.
1091
1092 .. envvar:: PYTHONLEGACYWINDOWSSTDIO
1093
1094 If set to a non-empty string, does not use the new console reader and
1095 writer. This means that Unicode characters will be encoded according to
1096 the active console code page, rather than using utf-8.
1097
1098 This variable is ignored if the standard streams are redirected (to files
1099 or pipes) rather than referring to console buffers.
1100
1101 .. availability:: Windows.
1102
1103 .. versionadded:: 3.6
1104
1105
1106 .. envvar:: PYTHONCOERCECLOCALE
1107
1108 If set to the value ``0``, causes the main Python command line application
1109 to skip coercing the legacy ASCII-based C and POSIX locales to a more
1110 capable UTF-8 based alternative.
1111
1112 If this variable is *not* set (or is set to a value other than ``0``), the
1113 ``LC_ALL`` locale override environment variable is also not set, and the
1114 current locale reported for the ``LC_CTYPE`` category is either the default
1115 ``C`` locale, or else the explicitly ASCII-based ``POSIX`` locale, then the
1116 Python CLI will attempt to configure the following locales for the
1117 ``LC_CTYPE`` category in the order listed before loading the interpreter
1118 runtime:
1119
1120 * ``C.UTF-8``
1121 * ``C.utf8``
1122 * ``UTF-8``
1123
1124 If setting one of these locale categories succeeds, then the ``LC_CTYPE``
1125 environment variable will also be set accordingly in the current process
1126 environment before the Python runtime is initialized. This ensures that in
1127 addition to being seen by both the interpreter itself and other locale-aware
1128 components running in the same process (such as the GNU ``readline``
1129 library), the updated setting is also seen in subprocesses (regardless of
1130 whether or not those processes are running a Python interpreter), as well as
1131 in operations that query the environment rather than the current C locale
1132 (such as Python's own :func:`locale.getdefaultlocale`).
1133
1134 Configuring one of these locales (either explicitly or via the above
1135 implicit locale coercion) automatically enables the ``surrogateescape``
1136 :ref:`error handler <error-handlers>` for :data:`sys.stdin` and
1137 :data:`sys.stdout` (:data:`sys.stderr` continues to use ``backslashreplace``
1138 as it does in any other locale). This stream handling behavior can be
1139 overridden using :envvar:`PYTHONIOENCODING` as usual.
1140
1141 For debugging purposes, setting ``PYTHONCOERCECLOCALE=warn`` will cause
1142 Python to emit warning messages on ``stderr`` if either the locale coercion
1143 activates, or else if a locale that *would* have triggered coercion is
1144 still active when the Python runtime is initialized.
1145
1146 Also note that even when locale coercion is disabled, or when it fails to
1147 find a suitable target locale, :envvar:`PYTHONUTF8` will still activate by
1148 default in legacy ASCII-based locales. Both features must be disabled in
1149 order to force the interpreter to use ``ASCII`` instead of ``UTF-8`` for
1150 system interfaces.
1151
1152 .. availability:: Unix.
1153
1154 .. versionadded:: 3.7
1155 See :pep:`538` for more details.
1156
1157
1158 .. envvar:: PYTHONDEVMODE
1159
1160 If this environment variable is set to a non-empty string, enable
1161 :ref:`Python Development Mode <devmode>`, introducing additional runtime
1162 checks that are too expensive to be enabled by default.
1163 This is equivalent to setting the :option:`-X` ``dev`` option.
1164
1165 .. versionadded:: 3.7
1166
1167 .. envvar:: PYTHONUTF8
1168
1169 If set to ``1``, enable the :ref:`Python UTF-8 Mode <utf8-mode>`.
1170
1171 If set to ``0``, disable the :ref:`Python UTF-8 Mode <utf8-mode>`.
1172
1173 Setting any other non-empty string causes an error during interpreter
1174 initialisation.
1175
1176 .. versionadded:: 3.7
1177
1178 .. envvar:: PYTHONWARNDEFAULTENCODING
1179
1180 If this environment variable is set to a non-empty string, issue a
1181 :class:`EncodingWarning` when the locale-specific default encoding is used.
1182
1183 See :ref:`io-encoding-warning` for details.
1184
1185 .. versionadded:: 3.10
1186
1187 .. envvar:: PYTHONNODEBUGRANGES
1188
1189 If this variable is set, it disables the inclusion of the tables mapping
1190 extra location information (end line, start column offset and end column
1191 offset) to every instruction in code objects. This is useful when smaller
1192 code objects and pyc files are desired as well as suppressing the extra visual
1193 location indicators when the interpreter displays tracebacks.
1194
1195 .. versionadded:: 3.11
1196
1197 .. envvar:: PYTHONPERFSUPPORT
1198
1199 If this variable is set to a nonzero value, it enables support for
1200 the Linux ``perf`` profiler so Python calls can be detected by it.
1201
1202 If set to ``0``, disable Linux ``perf`` profiler support.
1203
1204 See also the :option:`-X perf <-X>` command-line option
1205 and :ref:`perf_profiling`.
1206
1207 .. versionadded:: 3.12
1208
1209 .. envvar:: PYTHON_PERF_JIT_SUPPORT
1210
1211 If this variable is set to a nonzero value, it enables support for
1212 the Linux ``perf`` profiler so Python calls can be detected by it
1213 using DWARF information.
1214
1215 If set to ``0``, disable Linux ``perf`` profiler support.
1216
1217 See also the :option:`-X perf_jit <-X>` command-line option
1218 and :ref:`perf_profiling`.
1219
1220 .. versionadded:: 3.13
1221
1222 .. envvar:: PYTHON_DISABLE_REMOTE_DEBUG
1223
1224 If this variable is set to a non-empty string, it disables the remote
1225 debugging feature described in :pep:`768`. This includes both the functionality
1226 to schedule code for execution in another process and the functionality to
1227 receive code for execution in the current process.
1228
1229 See also the :option:`-X disable_remote_debug` command-line option.
1230
1231 .. versionadded:: 3.14
1232
1233 .. envvar:: PYTHON_CPU_COUNT
1234
1235 If this variable is set to a positive integer, it overrides the return
1236 values of :func:`os.cpu_count` and :func:`os.process_cpu_count`.
1237
1238 See also the :option:`-X cpu_count <-X>` command-line option.
1239
1240 .. versionadded:: 3.13
1241
1242 .. envvar:: PYTHON_FROZEN_MODULES
1243
1244 If this variable is set to ``on`` or ``off``, it determines whether or not
1245 frozen modules are ignored by the import machinery. A value of ``on`` means
1246 they get imported and ``off`` means they are ignored. The default is ``on``
1247 for non-debug builds (the normal case) and ``off`` for debug builds.
1248 Note that the :mod:`!importlib_bootstrap` and
1249 :mod:`!importlib_bootstrap_external` frozen modules are always used, even
1250 if this flag is set to ``off``.
1251
1252 See also the :option:`-X frozen_modules <-X>` command-line option.
1253
1254 .. versionadded:: 3.13
1255
1256 .. envvar:: PYTHON_COLORS
1257
1258 If this variable is set to ``1``, the interpreter will colorize various kinds
1259 of output. Setting it to ``0`` deactivates this behavior.
1260 See also :ref:`using-on-controlling-color`.
1261
1262 .. versionadded:: 3.13
1263
1264 .. envvar:: PYTHON_BASIC_REPL
1265
1266 If this variable is set to any value, the interpreter will not attempt to
1267 load the Python-based :term:`REPL` that requires :mod:`readline`, and will
1268 instead use the traditional parser-based :term:`REPL`.
1269
1270 .. versionadded:: 3.13
1271
1272 .. envvar:: PYTHON_HISTORY
1273
1274 This environment variable can be used to set the location of a
1275 ``.python_history`` file (by default, it is ``.python_history`` in the
1276 user's home directory).
1277
1278 .. versionadded:: 3.13
1279
1280 .. envvar:: PYTHON_GIL
1281
1282 If this variable is set to ``1``, the global interpreter lock (GIL) will be
1283 forced on. Setting it to ``0`` forces the GIL off (needs Python configured with
1284 the :option:`--disable-gil` build option).
1285
1286 See also the :option:`-X gil <-X>` command-line option, which takes
1287 precedence over this variable, and :ref:`whatsnew313-free-threaded-cpython`.
1288
1289 .. versionadded:: 3.13
1290
1291 .. envvar:: PYTHON_THREAD_INHERIT_CONTEXT
1292
1293 If this variable is set to ``1`` then :class:`~threading.Thread` will,
1294 by default, use a copy of context of the caller of ``Thread.start()``
1295 when starting. Otherwise, new threads will start with an empty context.
1296 If unset, this variable defaults to ``1`` on free-threaded builds and to
1297 ``0`` otherwise. See also :option:`-X thread_inherit_context<-X>`.
1298
1299 .. versionadded:: 3.14
1300
1301 .. envvar:: PYTHON_CONTEXT_AWARE_WARNINGS
1302
1303 If set to ``1`` then the :class:`warnings.catch_warnings` context
1304 manager will use a :class:`~contextvars.ContextVar` to store warnings
1305 filter state. If unset, this variable defaults to ``1`` on
1306 free-threaded builds and to ``0`` otherwise. See :option:`-X
1307 context_aware_warnings<-X>`.
1308
1309 .. versionadded:: 3.14
1310
1311 .. envvar:: PYTHON_JIT
1312
1313 On builds where experimental just-in-time compilation is available, this
1314 variable can force the JIT to be disabled (``0``) or enabled (``1``) at
1315 interpreter startup.
1316
1317 .. versionadded:: 3.13
1318
1319 .. envvar:: PYTHON_TLBC
1320
1321 If set to ``1`` enables thread-local bytecode. If set to ``0`` thread-local
1322 bytecode and the specializing interpreter are disabled. Only applies to
1323 builds configured with :option:`--disable-gil`.
1324
1325 See also the :option:`-X tlbc <-X>` command-line option.
1326
1327 .. versionadded:: 3.14
1328
1329 Debug-mode variables
1330 ~~~~~~~~~~~~~~~~~~~~
1331
1332 .. envvar:: PYTHONDUMPREFS
1333
1334 If set, Python will dump objects and reference counts still alive after
1335 shutting down the interpreter.
1336
1337 Needs Python configured with the :option:`--with-trace-refs` build option.
1338
1339 .. envvar:: PYTHONDUMPREFSFILE
1340
1341 If set, Python will dump objects and reference counts still alive
1342 after shutting down the interpreter into a file under the path given
1343 as the value to this environment variable.
1344
1345 Needs Python configured with the :option:`--with-trace-refs` build option.
1346
1347 .. versionadded:: 3.11
1348
1349 .. envvar:: PYTHON_PRESITE
1350
1351 If this variable is set to a module, that module will be imported
1352 early in the interpreter lifecycle, before the :mod:`site` module is
1353 executed, and before the :mod:`__main__` module is created.
1354 Therefore, the imported module is not treated as :mod:`__main__`.
1355
1356 This can be used to execute code early during Python initialization.
1357
1358 To import a submodule, use ``package.module`` as the value, like in
1359 an import statement.
1360
1361 See also the :option:`-X presite <-X>` command-line option,
1362 which takes precedence over this variable.
1363
1364 Needs Python configured with the :option:`--with-pydebug` build option.
1365
1366 .. versionadded:: 3.13