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 8Command line and environment 9============================ 10 11The CPython interpreter scans the command line and the environment for various 12settings. 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 22Command line 23------------ 24 25When invoking Python, you may specify any of these options:: 26 27 python [-bBdEhiIOqsSuvVWx?] [-c command | -m module-name | script | - ] [args] 28 29The 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 36Interface options 37~~~~~~~~~~~~~~~~~ 38 39The interpreter interface resembles that of the UNIX shell, but provides some 40additional 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* When called with a file name argument or with a file as standard input, it 46 reads and executes a script from that file. 47* When called with a directory name argument, it reads and executes an 48 appropriately named script from that directory. 49* When called with ``-c command``, it executes the Python statement(s) given as 50 *command*. Here *command* may contain multiple statements separated by 51 newlines. Leading whitespace is significant in Python statements! 52* When called with ``-m module-name``, the given module is located on the 53 Python module path and executed as a script. 54 55In non-interactive mode, the entire input is parsed before it is executed. 56 57An interface option terminates the list of options consumed by the interpreter, 58all consecutive arguments will end up in :data:`sys.argv` -- note that the first 59element, subscript zero (``sys.argv[0]``), is a string reflecting the program's 60source. 61 62.. cmdoption:: -c <command> 63 64 Execute the Python code in *command*. *command* can be one or more 65 statements separated by newlines, with significant leading whitespace as in 66 normal module code. 67 68 If this option is given, the first element of :data:`sys.argv` will be 69 ``"-c"`` and the current directory will be added to the start of 70 :data:`sys.path` (allowing modules in that directory to be imported as top 71 level modules). 72 73 .. audit-event:: cpython.run_command command cmdoption-c 74 75.. cmdoption:: -m <module-name> 76 77 Search :data:`sys.path` for the named module and execute its contents as 78 the :mod:`__main__` module. 79 80 Since the argument is a *module* name, you must not give a file extension 81 (``.py``). The module name should be a valid absolute Python module name, but 82 the implementation may not always enforce this (e.g. it may allow you to 83 use a name that includes a hyphen). 84 85 Package names (including namespace packages) are also permitted. When a 86 package name is supplied instead 87 of a normal module, the interpreter will execute ``<pkg>.__main__`` as 88 the main module. This behaviour is deliberately similar to the handling 89 of directories and zipfiles that are passed to the interpreter as the 90 script argument. 91 92 .. note:: 93 94 This option cannot be used with built-in modules and extension modules 95 written in C, since they do not have Python module files. However, it 96 can still be used for precompiled modules, even if the original source 97 file is not available. 98 99 If this option is given, the first element of :data:`sys.argv` will be the 100 full path to the module file (while the module file is being located, the 101 first element will be set to ``"-m"``). As with the :option:`-c` option, 102 the current directory will be added to the start of :data:`sys.path`. 103 104 :option:`-I` option can be used to run the script in isolated mode where 105 :data:`sys.path` contains neither the current directory nor the user's 106 site-packages directory. All :envvar:`PYTHON*` environment variables are 107 ignored, too. 108 109 Many standard library modules contain code that is invoked on their execution 110 as a script. An example is the :mod:`timeit` module:: 111 112 python -m timeit -s 'setup here' 'benchmarked code here' 113 python -m timeit -h # for details 114 115 .. audit-event:: cpython.run_module module-name cmdoption-m 116 117 .. seealso:: 118 :func:`runpy.run_module` 119 Equivalent functionality directly available to Python code 120 121 :pep:`338` -- Executing modules as scripts 122 123 .. versionchanged:: 3.1 124 Supply the package name to run a ``__main__`` submodule. 125 126 .. versionchanged:: 3.4 127 namespace packages are also supported 128 129.. _cmdarg-dash: 130 131.. describe:: - 132 133 Read commands from standard input (:data:`sys.stdin`). If standard input is 134 a terminal, :option:`-i` is implied. 135 136 If this option is given, the first element of :data:`sys.argv` will be 137 ``"-"`` and the current directory will be added to the start of 138 :data:`sys.path`. 139 140 .. audit-event:: cpython.run_stdin "" "" 141 142.. _cmdarg-script: 143 144.. describe:: <script> 145 146 Execute the Python code contained in *script*, which must be a filesystem 147 path (absolute or relative) referring to either a Python file, a directory 148 containing a ``__main__.py`` file, or a zipfile containing a 149 ``__main__.py`` file. 150 151 If this option is given, the first element of :data:`sys.argv` will be the 152 script name as given on the command line. 153 154 If the script name refers directly to a Python file, the directory 155 containing that file is added to the start of :data:`sys.path`, and the 156 file is executed as the :mod:`__main__` module. 157 158 If the script name refers to a directory or zipfile, the script name is 159 added to the start of :data:`sys.path` and the ``__main__.py`` file in 160 that location is executed as the :mod:`__main__` module. 161 162 :option:`-I` option can be used to run the script in isolated mode where 163 :data:`sys.path` contains neither the script's directory nor the user's 164 site-packages directory. All :envvar:`PYTHON*` environment variables are 165 ignored, too. 166 167 .. audit-event:: cpython.run_file filename 168 169 .. seealso:: 170 :func:`runpy.run_path` 171 Equivalent functionality directly available to Python code 172 173 174If no interface option is given, :option:`-i` is implied, ``sys.argv[0]`` is 175an empty string (``""``) and the current directory will be added to the 176start of :data:`sys.path`. Also, tab-completion and history editing is 177automatically enabled, if available on your platform (see 178:ref:`rlcompleter-config`). 179 180.. seealso:: :ref:`tut-invoking` 181 182.. versionchanged:: 3.4 183 Automatic enabling of tab-completion and history editing. 184 185 186Generic options 187~~~~~~~~~~~~~~~ 188 189.. cmdoption:: -? 190 -h 191 --help 192 193 Print a short description of all command line options. 194 195 196.. cmdoption:: -V 197 --version 198 199 Print the Python version number and exit. Example output could be: 200 201 .. code-block:: none 202 203 Python 3.8.0b2+ 204 205 When given twice, print more information about the build, like: 206 207 .. code-block:: none 208 209 Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00) 210 [GCC 6.2.0 20161005] 211 212 .. versionadded:: 3.6 213 The ``-VV`` option. 214 215.. _using-on-misc-options: 216 217Miscellaneous options 218~~~~~~~~~~~~~~~~~~~~~ 219 220.. cmdoption:: -b 221 222 Issue a warning when comparing :class:`bytes` or :class:`bytearray` with 223 :class:`str` or :class:`bytes` with :class:`int`. Issue an error when the 224 option is given twice (:option:`!-bb`). 225 226 .. versionchanged:: 3.5 227 Affects comparisons of :class:`bytes` with :class:`int`. 228 229.. cmdoption:: -B 230 231 If given, Python won't try to write ``.pyc`` files on the 232 import of source modules. See also :envvar:`PYTHONDONTWRITEBYTECODE`. 233 234 235.. cmdoption:: --check-hash-based-pycs default|always|never 236 237 Control the validation behavior of hash-based ``.pyc`` files. See 238 :ref:`pyc-invalidation`. When set to ``default``, checked and unchecked 239 hash-based bytecode cache files are validated according to their default 240 semantics. When set to ``always``, all hash-based ``.pyc`` files, whether 241 checked or unchecked, are validated against their corresponding source 242 file. When set to ``never``, hash-based ``.pyc`` files are not validated 243 against their corresponding source files. 244 245 The semantics of timestamp-based ``.pyc`` files are unaffected by this 246 option. 247 248 249.. cmdoption:: -d 250 251 Turn on parser debugging output (for expert only, depending on compilation 252 options). See also :envvar:`PYTHONDEBUG`. 253 254 255.. cmdoption:: -E 256 257 Ignore all :envvar:`PYTHON*` environment variables, e.g. 258 :envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set. 259 260 261.. cmdoption:: -i 262 263 When a script is passed as first argument or the :option:`-c` option is used, 264 enter interactive mode after executing the script or the command, even when 265 :data:`sys.stdin` does not appear to be a terminal. The 266 :envvar:`PYTHONSTARTUP` file is not read. 267 268 This can be useful to inspect global variables or a stack trace when a script 269 raises an exception. See also :envvar:`PYTHONINSPECT`. 270 271 272.. cmdoption:: -I 273 274 Run Python in isolated mode. This also implies -E and -s. 275 In isolated mode :data:`sys.path` contains neither the script's directory nor 276 the user's site-packages directory. All :envvar:`PYTHON*` environment 277 variables are ignored, too. Further restrictions may be imposed to prevent 278 the user from injecting malicious code. 279 280 .. versionadded:: 3.4 281 282 283.. cmdoption:: -O 284 285 Remove assert statements and any code conditional on the value of 286 :const:`__debug__`. Augment the filename for compiled 287 (:term:`bytecode`) files by adding ``.opt-1`` before the ``.pyc`` 288 extension (see :pep:`488`). See also :envvar:`PYTHONOPTIMIZE`. 289 290 .. versionchanged:: 3.5 291 Modify ``.pyc`` filenames according to :pep:`488`. 292 293 294.. cmdoption:: -OO 295 296 Do :option:`-O` and also discard docstrings. Augment the filename 297 for compiled (:term:`bytecode`) files by adding ``.opt-2`` before the 298 ``.pyc`` extension (see :pep:`488`). 299 300 .. versionchanged:: 3.5 301 Modify ``.pyc`` filenames according to :pep:`488`. 302 303 304.. cmdoption:: -q 305 306 Don't display the copyright and version messages even in interactive mode. 307 308 .. versionadded:: 3.2 309 310 311.. cmdoption:: -R 312 313 Turn on hash randomization. This option only has an effect if the 314 :envvar:`PYTHONHASHSEED` environment variable is set to ``0``, since hash 315 randomization is enabled by default. 316 317 On previous versions of Python, this option turns on hash randomization, 318 so that the :meth:`__hash__` values of str and bytes objects 319 are "salted" with an unpredictable random value. Although they remain 320 constant within an individual Python process, they are not predictable 321 between repeated invocations of Python. 322 323 Hash randomization is intended to provide protection against a 324 denial-of-service caused by carefully-chosen inputs that exploit the worst 325 case performance of a dict construction, O(n\ :sup:`2`) complexity. See 326 http://www.ocert.org/advisories/ocert-2011-003.html for details. 327 328 :envvar:`PYTHONHASHSEED` allows you to set a fixed value for the hash 329 seed secret. 330 331 .. versionchanged:: 3.7 332 The option is no longer ignored. 333 334 .. versionadded:: 3.2.3 335 336 337.. cmdoption:: -s 338 339 Don't add the :data:`user site-packages directory <site.USER_SITE>` to 340 :data:`sys.path`. 341 342 .. seealso:: 343 344 :pep:`370` -- Per user site-packages directory 345 346 347.. cmdoption:: -S 348 349 Disable the import of the module :mod:`site` and the site-dependent 350 manipulations of :data:`sys.path` that it entails. Also disable these 351 manipulations if :mod:`site` is explicitly imported later (call 352 :func:`site.main` if you want them to be triggered). 353 354 355.. cmdoption:: -u 356 357 Force the stdout and stderr streams to be unbuffered. This option has no 358 effect on the stdin stream. 359 360 See also :envvar:`PYTHONUNBUFFERED`. 361 362 .. versionchanged:: 3.7 363 The text layer of the stdout and stderr streams now is unbuffered. 364 365 366.. cmdoption:: -v 367 368 Print a message each time a module is initialized, showing the place 369 (filename or built-in module) from which it is loaded. When given twice 370 (:option:`!-vv`), print a message for each file that is checked for when 371 searching for a module. Also provides information on module cleanup at exit. 372 373 .. versionchanged:: 3.10 374 The :mod:`site` module reports the site-specific paths 375 and :file:`.pth` files being processed. 376 377 See also :envvar:`PYTHONVERBOSE`. 378 379 380.. _using-on-warnings: 381.. cmdoption:: -W arg 382 383 Warning control. Python's warning machinery by default prints warning 384 messages to :data:`sys.stderr`. 385 386 The simplest settings apply a particular action unconditionally to all 387 warnings emitted by a process (even those that are otherwise ignored by 388 default):: 389 390 -Wdefault # Warn once per call location 391 -Werror # Convert to exceptions 392 -Walways # Warn every time 393 -Wmodule # Warn once per calling module 394 -Wonce # Warn once per Python process 395 -Wignore # Never warn 396 397 The action names can be abbreviated as desired and the interpreter will 398 resolve them to the appropriate action name. For example, ``-Wi`` is the 399 same as ``-Wignore``. 400 401 The full form of argument is:: 402 403 action:message:category:module:lineno 404 405 Empty fields match all values; trailing empty fields may be omitted. For 406 example ``-W ignore::DeprecationWarning`` ignores all DeprecationWarning 407 warnings. 408 409 The *action* field is as explained above but only applies to warnings that 410 match the remaining fields. 411 412 The *message* field must match the whole warning message; this match is 413 case-insensitive. 414 415 The *category* field matches the warning category 416 (ex: ``DeprecationWarning``). This must be a class name; the match test 417 whether the actual warning category of the message is a subclass of the 418 specified warning category. 419 420 The *module* field matches the (fully-qualified) module name; this match is 421 case-sensitive. 422 423 The *lineno* field matches the line number, where zero matches all line 424 numbers and is thus equivalent to an omitted line number. 425 426 Multiple :option:`-W` options can be given; when a warning matches more than 427 one option, the action for the last matching option is performed. Invalid 428 :option:`-W` options are ignored (though, a warning message is printed about 429 invalid options when the first warning is issued). 430 431 Warnings can also be controlled using the :envvar:`PYTHONWARNINGS` 432 environment variable and from within a Python program using the 433 :mod:`warnings` module. For example, the :func:`warnings.filterwarnings` 434 function can be used to use a regular expression on the warning message. 435 436 See :ref:`warning-filter` and :ref:`describing-warning-filters` for more 437 details. 438 439.. cmdoption:: -x 440 441 Skip the first line of the source, allowing use of non-Unix forms of 442 ``#!cmd``. This is intended for a DOS specific hack only. 443 444 445.. cmdoption:: -X 446 447 Reserved for various implementation-specific options. CPython currently 448 defines the following possible values: 449 450 * ``-X faulthandler`` to enable :mod:`faulthandler`; 451 * ``-X showrefcount`` to output the total reference count and number of used 452 memory blocks when the program finishes or after each statement in the 453 interactive interpreter. This only works on :ref:`debug builds 454 <debug-build>`. 455 * ``-X tracemalloc`` to start tracing Python memory allocations using the 456 :mod:`tracemalloc` module. By default, only the most recent frame is 457 stored in a traceback of a trace. Use ``-X tracemalloc=NFRAME`` to start 458 tracing with a traceback limit of *NFRAME* frames. See the 459 :func:`tracemalloc.start` for more information. 460 * ``-X int_max_str_digits`` configures the :ref:`integer string conversion 461 length limitation <int_max_str_digits>`. See also 462 :envvar:`PYTHONINTMAXSTRDIGITS`. 463 * ``-X importtime`` to show how long each import takes. It shows module 464 name, cumulative time (including nested imports) and self time (excluding 465 nested imports). Note that its output may be broken in multi-threaded 466 application. Typical usage is ``python3 -X importtime -c 'import 467 asyncio'``. See also :envvar:`PYTHONPROFILEIMPORTTIME`. 468 * ``-X dev``: enable :ref:`Python Development Mode <devmode>`, introducing 469 additional runtime checks that are too expensive to be enabled by 470 default. 471 * ``-X utf8`` enables the :ref:`Python UTF-8 Mode <utf8-mode>`. 472 ``-X utf8=0`` explicitly disables :ref:`Python UTF-8 Mode <utf8-mode>` 473 (even when it would otherwise activate automatically). 474 * ``-X pycache_prefix=PATH`` enables writing ``.pyc`` files to a parallel 475 tree rooted at the given directory instead of to the code tree. See also 476 :envvar:`PYTHONPYCACHEPREFIX`. 477 * ``-X warn_default_encoding`` issues a :class:`EncodingWarning` when the 478 locale-specific default encoding is used for opening files. 479 See also :envvar:`PYTHONWARNDEFAULTENCODING`. 480 481 It also allows passing arbitrary values and retrieving them through the 482 :data:`sys._xoptions` dictionary. 483 484 .. versionchanged:: 3.2 485 The :option:`-X` option was added. 486 487 .. versionadded:: 3.3 488 The ``-X faulthandler`` option. 489 490 .. versionadded:: 3.4 491 The ``-X showrefcount`` and ``-X tracemalloc`` options. 492 493 .. versionadded:: 3.6 494 The ``-X showalloccount`` option. 495 496 .. versionadded:: 3.7 497 The ``-X importtime``, ``-X dev`` and ``-X utf8`` options. 498 499 .. versionadded:: 3.8 500 The ``-X pycache_prefix`` option. The ``-X dev`` option now logs 501 ``close()`` exceptions in :class:`io.IOBase` destructor. 502 503 .. versionchanged:: 3.9 504 Using ``-X dev`` option, check *encoding* and *errors* arguments on 505 string encoding and decoding operations. 506 507 The ``-X showalloccount`` option has been removed. 508 509 .. versionadded:: 3.10 510 The ``-X warn_default_encoding`` option. 511 512 .. versionadded:: 3.10.7 513 The ``-X int_max_str_digits`` option. 514 515 .. deprecated-removed:: 3.9 3.10 516 The ``-X oldparser`` option. 517 518 519Options you shouldn't use 520~~~~~~~~~~~~~~~~~~~~~~~~~ 521 522.. cmdoption:: -J 523 524 Reserved for use by Jython_. 525 526.. _Jython: http://www.jython.org/ 527 528.. _using-on-envvars: 529 530Environment variables 531--------------------- 532 533These environment variables influence Python's behavior, they are processed 534before the command-line switches other than -E or -I. It is customary that 535command-line switches override environmental variables where there is a 536conflict. 537 538.. envvar:: PYTHONHOME 539 540 Change the location of the standard Python libraries. By default, the 541 libraries are searched in :file:`{prefix}/lib/python{version}` and 542 :file:`{exec_prefix}/lib/python{version}`, where :file:`{prefix}` and 543 :file:`{exec_prefix}` are installation-dependent directories, both defaulting 544 to :file:`/usr/local`. 545 546 When :envvar:`PYTHONHOME` is set to a single directory, its value replaces 547 both :file:`{prefix}` and :file:`{exec_prefix}`. To specify different values 548 for these, set :envvar:`PYTHONHOME` to :file:`{prefix}:{exec_prefix}`. 549 550 551.. envvar:: PYTHONPATH 552 553 Augment the default search path for module files. The format is the same as 554 the shell's :envvar:`PATH`: one or more directory pathnames separated by 555 :data:`os.pathsep` (e.g. colons on Unix or semicolons on Windows). 556 Non-existent directories are silently ignored. 557 558 In addition to normal directories, individual :envvar:`PYTHONPATH` entries 559 may refer to zipfiles containing pure Python modules (in either source or 560 compiled form). Extension modules cannot be imported from zipfiles. 561 562 The default search path is installation dependent, but generally begins with 563 :file:`{prefix}/lib/python{version}` (see :envvar:`PYTHONHOME` above). It 564 is *always* appended to :envvar:`PYTHONPATH`. 565 566 An additional directory will be inserted in the search path in front of 567 :envvar:`PYTHONPATH` as described above under 568 :ref:`using-on-interface-options`. The search path can be manipulated from 569 within a Python program as the variable :data:`sys.path`. 570 571 572.. envvar:: PYTHONPLATLIBDIR 573 574 If this is set to a non-empty string, it overrides the :data:`sys.platlibdir` 575 value. 576 577 .. versionadded:: 3.9 578 579 580.. envvar:: PYTHONSTARTUP 581 582 If this is the name of a readable file, the Python commands in that file are 583 executed before the first prompt is displayed in interactive mode. The file 584 is executed in the same namespace where interactive commands are executed so 585 that objects defined or imported in it can be used without qualification in 586 the interactive session. You can also change the prompts :data:`sys.ps1` and 587 :data:`sys.ps2` and the hook :data:`sys.__interactivehook__` in this file. 588 589 .. audit-event:: cpython.run_startup filename envvar-PYTHONSTARTUP 590 591 Raises an :ref:`auditing event <auditing>` ``cpython.run_startup`` with 592 the filename as the argument when called on startup. 593 594 595.. envvar:: PYTHONOPTIMIZE 596 597 If this is set to a non-empty string it is equivalent to specifying the 598 :option:`-O` option. If set to an integer, it is equivalent to specifying 599 :option:`-O` multiple times. 600 601 602.. envvar:: PYTHONBREAKPOINT 603 604 If this is set, it names a callable using dotted-path notation. The module 605 containing the callable will be imported and then the callable will be run 606 by the default implementation of :func:`sys.breakpointhook` which itself is 607 called by built-in :func:`breakpoint`. If not set, or set to the empty 608 string, it is equivalent to the value "pdb.set_trace". Setting this to the 609 string "0" causes the default implementation of :func:`sys.breakpointhook` 610 to do nothing but return immediately. 611 612 .. versionadded:: 3.7 613 614.. envvar:: PYTHONDEBUG 615 616 If this is set to a non-empty string it is equivalent to specifying the 617 :option:`-d` option. If set to an integer, it is equivalent to specifying 618 :option:`-d` multiple times. 619 620 621.. envvar:: PYTHONINSPECT 622 623 If this is set to a non-empty string it is equivalent to specifying the 624 :option:`-i` option. 625 626 This variable can also be modified by Python code using :data:`os.environ` 627 to force inspect mode on program termination. 628 629 630.. envvar:: PYTHONUNBUFFERED 631 632 If this is set to a non-empty string it is equivalent to specifying the 633 :option:`-u` option. 634 635 636.. envvar:: PYTHONVERBOSE 637 638 If this is set to a non-empty string it is equivalent to specifying the 639 :option:`-v` option. If set to an integer, it is equivalent to specifying 640 :option:`-v` multiple times. 641 642 643.. envvar:: PYTHONCASEOK 644 645 If this is set, Python ignores case in :keyword:`import` statements. This 646 only works on Windows and macOS. 647 648 649.. envvar:: PYTHONDONTWRITEBYTECODE 650 651 If this is set to a non-empty string, Python won't try to write ``.pyc`` 652 files on the import of source modules. This is equivalent to 653 specifying the :option:`-B` option. 654 655 656.. envvar:: PYTHONPYCACHEPREFIX 657 658 If this is set, Python will write ``.pyc`` files in a mirror directory tree 659 at this path, instead of in ``__pycache__`` directories within the source 660 tree. This is equivalent to specifying the :option:`-X` 661 ``pycache_prefix=PATH`` option. 662 663 .. versionadded:: 3.8 664 665 666.. envvar:: PYTHONHASHSEED 667 668 If this variable is not set or set to ``random``, a random value is used 669 to seed the hashes of str and bytes objects. 670 671 If :envvar:`PYTHONHASHSEED` is set to an integer value, it is used as a fixed 672 seed for generating the hash() of the types covered by the hash 673 randomization. 674 675 Its purpose is to allow repeatable hashing, such as for selftests for the 676 interpreter itself, or to allow a cluster of python processes to share hash 677 values. 678 679 The integer must be a decimal number in the range [0,4294967295]. Specifying 680 the value 0 will disable hash randomization. 681 682 .. versionadded:: 3.2.3 683 684.. envvar:: PYTHONINTMAXSTRDIGITS 685 686 If this variable is set to an integer, it is used to configure the 687 interpreter's global :ref:`integer string conversion length limitation 688 <int_max_str_digits>`. 689 690 .. versionadded:: 3.10.7 691 692.. envvar:: PYTHONIOENCODING 693 694 If this is set before running the interpreter, it overrides the encoding used 695 for stdin/stdout/stderr, in the syntax ``encodingname:errorhandler``. Both 696 the ``encodingname`` and the ``:errorhandler`` parts are optional and have 697 the same meaning as in :func:`str.encode`. 698 699 For stderr, the ``:errorhandler`` part is ignored; the handler will always be 700 ``'backslashreplace'``. 701 702 .. versionchanged:: 3.4 703 The ``encodingname`` part is now optional. 704 705 .. versionchanged:: 3.6 706 On Windows, the encoding specified by this variable is ignored for interactive 707 console buffers unless :envvar:`PYTHONLEGACYWINDOWSSTDIO` is also specified. 708 Files and pipes redirected through the standard streams are not affected. 709 710.. envvar:: PYTHONNOUSERSITE 711 712 If this is set, Python won't add the :data:`user site-packages directory 713 <site.USER_SITE>` to :data:`sys.path`. 714 715 .. seealso:: 716 717 :pep:`370` -- Per user site-packages directory 718 719 720.. envvar:: PYTHONUSERBASE 721 722 Defines the :data:`user base directory <site.USER_BASE>`, which is used to 723 compute the path of the :data:`user site-packages directory <site.USER_SITE>` 724 and :ref:`Distutils installation paths <inst-alt-install-user>` for 725 ``python setup.py install --user``. 726 727 .. seealso:: 728 729 :pep:`370` -- Per user site-packages directory 730 731 732.. envvar:: PYTHONEXECUTABLE 733 734 If this environment variable is set, ``sys.argv[0]`` will be set to its 735 value instead of the value got through the C runtime. Only works on 736 macOS. 737 738.. envvar:: PYTHONWARNINGS 739 740 This is equivalent to the :option:`-W` option. If set to a comma 741 separated string, it is equivalent to specifying :option:`-W` multiple 742 times, with filters later in the list taking precedence over those earlier 743 in the list. 744 745 The simplest settings apply a particular action unconditionally to all 746 warnings emitted by a process (even those that are otherwise ignored by 747 default):: 748 749 PYTHONWARNINGS=default # Warn once per call location 750 PYTHONWARNINGS=error # Convert to exceptions 751 PYTHONWARNINGS=always # Warn every time 752 PYTHONWARNINGS=module # Warn once per calling module 753 PYTHONWARNINGS=once # Warn once per Python process 754 PYTHONWARNINGS=ignore # Never warn 755 756 See :ref:`warning-filter` and :ref:`describing-warning-filters` for more 757 details. 758 759 760.. envvar:: PYTHONFAULTHANDLER 761 762 If this environment variable is set to a non-empty string, 763 :func:`faulthandler.enable` is called at startup: install a handler for 764 :const:`SIGSEGV`, :const:`SIGFPE`, :const:`SIGABRT`, :const:`SIGBUS` and 765 :const:`SIGILL` signals to dump the Python traceback. This is equivalent to 766 :option:`-X` ``faulthandler`` option. 767 768 .. versionadded:: 3.3 769 770 771.. envvar:: PYTHONTRACEMALLOC 772 773 If this environment variable is set to a non-empty string, start tracing 774 Python memory allocations using the :mod:`tracemalloc` module. The value of 775 the variable is the maximum number of frames stored in a traceback of a 776 trace. For example, ``PYTHONTRACEMALLOC=1`` stores only the most recent 777 frame. See the :func:`tracemalloc.start` for more information. 778 779 .. versionadded:: 3.4 780 781 782.. envvar:: PYTHONPROFILEIMPORTTIME 783 784 If this environment variable is set to a non-empty string, Python will 785 show how long each import takes. This is exactly equivalent to setting 786 ``-X importtime`` on the command line. 787 788 .. versionadded:: 3.7 789 790 791.. envvar:: PYTHONASYNCIODEBUG 792 793 If this environment variable is set to a non-empty string, enable the 794 :ref:`debug mode <asyncio-debug-mode>` of the :mod:`asyncio` module. 795 796 .. versionadded:: 3.4 797 798 799.. envvar:: PYTHONMALLOC 800 801 Set the Python memory allocators and/or install debug hooks. 802 803 Set the family of memory allocators used by Python: 804 805 * ``default``: use the :ref:`default memory allocators 806 <default-memory-allocators>`. 807 * ``malloc``: use the :c:func:`malloc` function of the C library 808 for all domains (:c:data:`PYMEM_DOMAIN_RAW`, :c:data:`PYMEM_DOMAIN_MEM`, 809 :c:data:`PYMEM_DOMAIN_OBJ`). 810 * ``pymalloc``: use the :ref:`pymalloc allocator <pymalloc>` for 811 :c:data:`PYMEM_DOMAIN_MEM` and :c:data:`PYMEM_DOMAIN_OBJ` domains and use 812 the :c:func:`malloc` function for the :c:data:`PYMEM_DOMAIN_RAW` domain. 813 814 Install :ref:`debug hooks <pymem-debug-hooks>`: 815 816 * ``debug``: install debug hooks on top of the :ref:`default memory 817 allocators <default-memory-allocators>`. 818 * ``malloc_debug``: same as ``malloc`` but also install debug hooks. 819 * ``pymalloc_debug``: same as ``pymalloc`` but also install debug hooks. 820 821 .. versionchanged:: 3.7 822 Added the ``"default"`` allocator. 823 824 .. versionadded:: 3.6 825 826 827.. envvar:: PYTHONMALLOCSTATS 828 829 If set to a non-empty string, Python will print statistics of the 830 :ref:`pymalloc memory allocator <pymalloc>` every time a new pymalloc object 831 arena is created, and on shutdown. 832 833 This variable is ignored if the :envvar:`PYTHONMALLOC` environment variable 834 is used to force the :c:func:`malloc` allocator of the C library, or if 835 Python is configured without ``pymalloc`` support. 836 837 .. versionchanged:: 3.6 838 This variable can now also be used on Python compiled in release mode. 839 It now has no effect if set to an empty string. 840 841 842.. envvar:: PYTHONLEGACYWINDOWSFSENCODING 843 844 If set to a non-empty string, the default :term:`filesystem encoding and 845 error handler` mode will revert to their pre-3.6 values of 'mbcs' and 846 'replace', respectively. Otherwise, the new defaults 'utf-8' and 847 'surrogatepass' are used. 848 849 This may also be enabled at runtime with 850 :func:`sys._enablelegacywindowsfsencoding()`. 851 852 .. availability:: Windows. 853 854 .. versionadded:: 3.6 855 See :pep:`529` for more details. 856 857.. envvar:: PYTHONLEGACYWINDOWSSTDIO 858 859 If set to a non-empty string, does not use the new console reader and 860 writer. This means that Unicode characters will be encoded according to 861 the active console code page, rather than using utf-8. 862 863 This variable is ignored if the standard streams are redirected (to files 864 or pipes) rather than referring to console buffers. 865 866 .. availability:: Windows. 867 868 .. versionadded:: 3.6 869 870 871.. envvar:: PYTHONCOERCECLOCALE 872 873 If set to the value ``0``, causes the main Python command line application 874 to skip coercing the legacy ASCII-based C and POSIX locales to a more 875 capable UTF-8 based alternative. 876 877 If this variable is *not* set (or is set to a value other than ``0``), the 878 ``LC_ALL`` locale override environment variable is also not set, and the 879 current locale reported for the ``LC_CTYPE`` category is either the default 880 ``C`` locale, or else the explicitly ASCII-based ``POSIX`` locale, then the 881 Python CLI will attempt to configure the following locales for the 882 ``LC_CTYPE`` category in the order listed before loading the interpreter 883 runtime: 884 885 * ``C.UTF-8`` 886 * ``C.utf8`` 887 * ``UTF-8`` 888 889 If setting one of these locale categories succeeds, then the ``LC_CTYPE`` 890 environment variable will also be set accordingly in the current process 891 environment before the Python runtime is initialized. This ensures that in 892 addition to being seen by both the interpreter itself and other locale-aware 893 components running in the same process (such as the GNU ``readline`` 894 library), the updated setting is also seen in subprocesses (regardless of 895 whether or not those processes are running a Python interpreter), as well as 896 in operations that query the environment rather than the current C locale 897 (such as Python's own :func:`locale.getdefaultlocale`). 898 899 Configuring one of these locales (either explicitly or via the above 900 implicit locale coercion) automatically enables the ``surrogateescape`` 901 :ref:`error handler <error-handlers>` for :data:`sys.stdin` and 902 :data:`sys.stdout` (:data:`sys.stderr` continues to use ``backslashreplace`` 903 as it does in any other locale). This stream handling behavior can be 904 overridden using :envvar:`PYTHONIOENCODING` as usual. 905 906 For debugging purposes, setting ``PYTHONCOERCECLOCALE=warn`` will cause 907 Python to emit warning messages on ``stderr`` if either the locale coercion 908 activates, or else if a locale that *would* have triggered coercion is 909 still active when the Python runtime is initialized. 910 911 Also note that even when locale coercion is disabled, or when it fails to 912 find a suitable target locale, :envvar:`PYTHONUTF8` will still activate by 913 default in legacy ASCII-based locales. Both features must be disabled in 914 order to force the interpreter to use ``ASCII`` instead of ``UTF-8`` for 915 system interfaces. 916 917 .. availability:: \*nix. 918 919 .. versionadded:: 3.7 920 See :pep:`538` for more details. 921 922 923.. envvar:: PYTHONDEVMODE 924 925 If this environment variable is set to a non-empty string, enable 926 :ref:`Python Development Mode <devmode>`, introducing additional runtime 927 checks that are too expensive to be enabled by default. 928 929 .. versionadded:: 3.7 930 931.. envvar:: PYTHONUTF8 932 933 If set to ``1``, enable the :ref:`Python UTF-8 Mode <utf8-mode>`. 934 935 If set to ``0``, disable the :ref:`Python UTF-8 Mode <utf8-mode>`. 936 937 Setting any other non-empty string causes an error during interpreter 938 initialisation. 939 940 .. versionadded:: 3.7 941 942.. envvar:: PYTHONWARNDEFAULTENCODING 943 944 If this environment variable is set to a non-empty string, issue a 945 :class:`EncodingWarning` when the locale-specific default encoding is used. 946 947 See :ref:`io-encoding-warning` for details. 948 949 .. versionadded:: 3.10 950 951 952Debug-mode variables 953~~~~~~~~~~~~~~~~~~~~ 954 955.. envvar:: PYTHONTHREADDEBUG 956 957 If set, Python will print threading debug info into stdout. 958 959 Need a :ref:`debug build of Python <debug-build>`. 960 961 .. deprecated-removed:: 3.10 3.12 962 963 964.. envvar:: PYTHONDUMPREFS 965 966 If set, Python will dump objects and reference counts still alive after 967 shutting down the interpreter. 968 969 Need Python configured with the :option:`--with-trace-refs` build option. 970