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 importtime`` to show how long each import takes. It shows module 461 name, cumulative time (including nested imports) and self time (excluding 462 nested imports). Note that its output may be broken in multi-threaded 463 application. Typical usage is ``python3 -X importtime -c 'import 464 asyncio'``. See also :envvar:`PYTHONPROFILEIMPORTTIME`. 465 * ``-X dev``: enable :ref:`Python Development Mode <devmode>`, introducing 466 additional runtime checks that are too expensive to be enabled by 467 default. 468 * ``-X utf8`` enables the :ref:`Python UTF-8 Mode <utf8-mode>`. 469 ``-X utf8=0`` explicitly disables :ref:`Python UTF-8 Mode <utf8-mode>` 470 (even when it would otherwise activate automatically). 471 * ``-X pycache_prefix=PATH`` enables writing ``.pyc`` files to a parallel 472 tree rooted at the given directory instead of to the code tree. See also 473 :envvar:`PYTHONPYCACHEPREFIX`. 474 * ``-X warn_default_encoding`` issues a :class:`EncodingWarning` when the 475 locale-specific default encoding is used for opening files. 476 See also :envvar:`PYTHONWARNDEFAULTENCODING`. 477 478 It also allows passing arbitrary values and retrieving them through the 479 :data:`sys._xoptions` dictionary. 480 481 .. versionchanged:: 3.2 482 The :option:`-X` option was added. 483 484 .. versionadded:: 3.3 485 The ``-X faulthandler`` option. 486 487 .. versionadded:: 3.4 488 The ``-X showrefcount`` and ``-X tracemalloc`` options. 489 490 .. versionadded:: 3.6 491 The ``-X showalloccount`` option. 492 493 .. versionadded:: 3.7 494 The ``-X importtime``, ``-X dev`` and ``-X utf8`` options. 495 496 .. versionadded:: 3.8 497 The ``-X pycache_prefix`` option. The ``-X dev`` option now logs 498 ``close()`` exceptions in :class:`io.IOBase` destructor. 499 500 .. versionchanged:: 3.9 501 Using ``-X dev`` option, check *encoding* and *errors* arguments on 502 string encoding and decoding operations. 503 504 The ``-X showalloccount`` option has been removed. 505 506 .. versionadded:: 3.10 507 The ``-X warn_default_encoding`` option. 508 509 .. deprecated-removed:: 3.9 3.10 510 The ``-X oldparser`` option. 511 512 513Options you shouldn't use 514~~~~~~~~~~~~~~~~~~~~~~~~~ 515 516.. cmdoption:: -J 517 518 Reserved for use by Jython_. 519 520.. _Jython: http://www.jython.org/ 521 522 523.. _using-on-envvars: 524 525Environment variables 526--------------------- 527 528These environment variables influence Python's behavior, they are processed 529before the command-line switches other than -E or -I. It is customary that 530command-line switches override environmental variables where there is a 531conflict. 532 533.. envvar:: PYTHONHOME 534 535 Change the location of the standard Python libraries. By default, the 536 libraries are searched in :file:`{prefix}/lib/python{version}` and 537 :file:`{exec_prefix}/lib/python{version}`, where :file:`{prefix}` and 538 :file:`{exec_prefix}` are installation-dependent directories, both defaulting 539 to :file:`/usr/local`. 540 541 When :envvar:`PYTHONHOME` is set to a single directory, its value replaces 542 both :file:`{prefix}` and :file:`{exec_prefix}`. To specify different values 543 for these, set :envvar:`PYTHONHOME` to :file:`{prefix}:{exec_prefix}`. 544 545 546.. envvar:: PYTHONPATH 547 548 Augment the default search path for module files. The format is the same as 549 the shell's :envvar:`PATH`: one or more directory pathnames separated by 550 :data:`os.pathsep` (e.g. colons on Unix or semicolons on Windows). 551 Non-existent directories are silently ignored. 552 553 In addition to normal directories, individual :envvar:`PYTHONPATH` entries 554 may refer to zipfiles containing pure Python modules (in either source or 555 compiled form). Extension modules cannot be imported from zipfiles. 556 557 The default search path is installation dependent, but generally begins with 558 :file:`{prefix}/lib/python{version}` (see :envvar:`PYTHONHOME` above). It 559 is *always* appended to :envvar:`PYTHONPATH`. 560 561 An additional directory will be inserted in the search path in front of 562 :envvar:`PYTHONPATH` as described above under 563 :ref:`using-on-interface-options`. The search path can be manipulated from 564 within a Python program as the variable :data:`sys.path`. 565 566 567.. envvar:: PYTHONPLATLIBDIR 568 569 If this is set to a non-empty string, it overrides the :data:`sys.platlibdir` 570 value. 571 572 .. versionadded:: 3.9 573 574 575.. envvar:: PYTHONSTARTUP 576 577 If this is the name of a readable file, the Python commands in that file are 578 executed before the first prompt is displayed in interactive mode. The file 579 is executed in the same namespace where interactive commands are executed so 580 that objects defined or imported in it can be used without qualification in 581 the interactive session. You can also change the prompts :data:`sys.ps1` and 582 :data:`sys.ps2` and the hook :data:`sys.__interactivehook__` in this file. 583 584 .. audit-event:: cpython.run_startup filename envvar-PYTHONSTARTUP 585 586 Raises an :ref:`auditing event <auditing>` ``cpython.run_startup`` with 587 the filename as the argument when called on startup. 588 589 590.. envvar:: PYTHONOPTIMIZE 591 592 If this is set to a non-empty string it is equivalent to specifying the 593 :option:`-O` option. If set to an integer, it is equivalent to specifying 594 :option:`-O` multiple times. 595 596 597.. envvar:: PYTHONBREAKPOINT 598 599 If this is set, it names a callable using dotted-path notation. The module 600 containing the callable will be imported and then the callable will be run 601 by the default implementation of :func:`sys.breakpointhook` which itself is 602 called by built-in :func:`breakpoint`. If not set, or set to the empty 603 string, it is equivalent to the value "pdb.set_trace". Setting this to the 604 string "0" causes the default implementation of :func:`sys.breakpointhook` 605 to do nothing but return immediately. 606 607 .. versionadded:: 3.7 608 609.. envvar:: PYTHONDEBUG 610 611 If this is set to a non-empty string it is equivalent to specifying the 612 :option:`-d` option. If set to an integer, it is equivalent to specifying 613 :option:`-d` multiple times. 614 615 616.. envvar:: PYTHONINSPECT 617 618 If this is set to a non-empty string it is equivalent to specifying the 619 :option:`-i` option. 620 621 This variable can also be modified by Python code using :data:`os.environ` 622 to force inspect mode on program termination. 623 624 625.. envvar:: PYTHONUNBUFFERED 626 627 If this is set to a non-empty string it is equivalent to specifying the 628 :option:`-u` option. 629 630 631.. envvar:: PYTHONVERBOSE 632 633 If this is set to a non-empty string it is equivalent to specifying the 634 :option:`-v` option. If set to an integer, it is equivalent to specifying 635 :option:`-v` multiple times. 636 637 638.. envvar:: PYTHONCASEOK 639 640 If this is set, Python ignores case in :keyword:`import` statements. This 641 only works on Windows and macOS. 642 643 644.. envvar:: PYTHONDONTWRITEBYTECODE 645 646 If this is set to a non-empty string, Python won't try to write ``.pyc`` 647 files on the import of source modules. This is equivalent to 648 specifying the :option:`-B` option. 649 650 651.. envvar:: PYTHONPYCACHEPREFIX 652 653 If this is set, Python will write ``.pyc`` files in a mirror directory tree 654 at this path, instead of in ``__pycache__`` directories within the source 655 tree. This is equivalent to specifying the :option:`-X` 656 ``pycache_prefix=PATH`` option. 657 658 .. versionadded:: 3.8 659 660 661.. envvar:: PYTHONHASHSEED 662 663 If this variable is not set or set to ``random``, a random value is used 664 to seed the hashes of str and bytes objects. 665 666 If :envvar:`PYTHONHASHSEED` is set to an integer value, it is used as a fixed 667 seed for generating the hash() of the types covered by the hash 668 randomization. 669 670 Its purpose is to allow repeatable hashing, such as for selftests for the 671 interpreter itself, or to allow a cluster of python processes to share hash 672 values. 673 674 The integer must be a decimal number in the range [0,4294967295]. Specifying 675 the value 0 will disable hash randomization. 676 677 .. versionadded:: 3.2.3 678 679 680.. envvar:: PYTHONIOENCODING 681 682 If this is set before running the interpreter, it overrides the encoding used 683 for stdin/stdout/stderr, in the syntax ``encodingname:errorhandler``. Both 684 the ``encodingname`` and the ``:errorhandler`` parts are optional and have 685 the same meaning as in :func:`str.encode`. 686 687 For stderr, the ``:errorhandler`` part is ignored; the handler will always be 688 ``'backslashreplace'``. 689 690 .. versionchanged:: 3.4 691 The ``encodingname`` part is now optional. 692 693 .. versionchanged:: 3.6 694 On Windows, the encoding specified by this variable is ignored for interactive 695 console buffers unless :envvar:`PYTHONLEGACYWINDOWSSTDIO` is also specified. 696 Files and pipes redirected through the standard streams are not affected. 697 698.. envvar:: PYTHONNOUSERSITE 699 700 If this is set, Python won't add the :data:`user site-packages directory 701 <site.USER_SITE>` to :data:`sys.path`. 702 703 .. seealso:: 704 705 :pep:`370` -- Per user site-packages directory 706 707 708.. envvar:: PYTHONUSERBASE 709 710 Defines the :data:`user base directory <site.USER_BASE>`, which is used to 711 compute the path of the :data:`user site-packages directory <site.USER_SITE>` 712 and :ref:`Distutils installation paths <inst-alt-install-user>` for 713 ``python setup.py install --user``. 714 715 .. seealso:: 716 717 :pep:`370` -- Per user site-packages directory 718 719 720.. envvar:: PYTHONEXECUTABLE 721 722 If this environment variable is set, ``sys.argv[0]`` will be set to its 723 value instead of the value got through the C runtime. Only works on 724 macOS. 725 726.. envvar:: PYTHONWARNINGS 727 728 This is equivalent to the :option:`-W` option. If set to a comma 729 separated string, it is equivalent to specifying :option:`-W` multiple 730 times, with filters later in the list taking precedence over those earlier 731 in the list. 732 733 The simplest settings apply a particular action unconditionally to all 734 warnings emitted by a process (even those that are otherwise ignored by 735 default):: 736 737 PYTHONWARNINGS=default # Warn once per call location 738 PYTHONWARNINGS=error # Convert to exceptions 739 PYTHONWARNINGS=always # Warn every time 740 PYTHONWARNINGS=module # Warn once per calling module 741 PYTHONWARNINGS=once # Warn once per Python process 742 PYTHONWARNINGS=ignore # Never warn 743 744 See :ref:`warning-filter` and :ref:`describing-warning-filters` for more 745 details. 746 747 748.. envvar:: PYTHONFAULTHANDLER 749 750 If this environment variable is set to a non-empty string, 751 :func:`faulthandler.enable` is called at startup: install a handler for 752 :const:`SIGSEGV`, :const:`SIGFPE`, :const:`SIGABRT`, :const:`SIGBUS` and 753 :const:`SIGILL` signals to dump the Python traceback. This is equivalent to 754 :option:`-X` ``faulthandler`` option. 755 756 .. versionadded:: 3.3 757 758 759.. envvar:: PYTHONTRACEMALLOC 760 761 If this environment variable is set to a non-empty string, start tracing 762 Python memory allocations using the :mod:`tracemalloc` module. The value of 763 the variable is the maximum number of frames stored in a traceback of a 764 trace. For example, ``PYTHONTRACEMALLOC=1`` stores only the most recent 765 frame. See the :func:`tracemalloc.start` for more information. 766 767 .. versionadded:: 3.4 768 769 770.. envvar:: PYTHONPROFILEIMPORTTIME 771 772 If this environment variable is set to a non-empty string, Python will 773 show how long each import takes. This is exactly equivalent to setting 774 ``-X importtime`` on the command line. 775 776 .. versionadded:: 3.7 777 778 779.. envvar:: PYTHONASYNCIODEBUG 780 781 If this environment variable is set to a non-empty string, enable the 782 :ref:`debug mode <asyncio-debug-mode>` of the :mod:`asyncio` module. 783 784 .. versionadded:: 3.4 785 786 787.. envvar:: PYTHONMALLOC 788 789 Set the Python memory allocators and/or install debug hooks. 790 791 Set the family of memory allocators used by Python: 792 793 * ``default``: use the :ref:`default memory allocators 794 <default-memory-allocators>`. 795 * ``malloc``: use the :c:func:`malloc` function of the C library 796 for all domains (:c:data:`PYMEM_DOMAIN_RAW`, :c:data:`PYMEM_DOMAIN_MEM`, 797 :c:data:`PYMEM_DOMAIN_OBJ`). 798 * ``pymalloc``: use the :ref:`pymalloc allocator <pymalloc>` for 799 :c:data:`PYMEM_DOMAIN_MEM` and :c:data:`PYMEM_DOMAIN_OBJ` domains and use 800 the :c:func:`malloc` function for the :c:data:`PYMEM_DOMAIN_RAW` domain. 801 802 Install :ref:`debug hooks <pymem-debug-hooks>`: 803 804 * ``debug``: install debug hooks on top of the :ref:`default memory 805 allocators <default-memory-allocators>`. 806 * ``malloc_debug``: same as ``malloc`` but also install debug hooks. 807 * ``pymalloc_debug``: same as ``pymalloc`` but also install debug hooks. 808 809 .. versionchanged:: 3.7 810 Added the ``"default"`` allocator. 811 812 .. versionadded:: 3.6 813 814 815.. envvar:: PYTHONMALLOCSTATS 816 817 If set to a non-empty string, Python will print statistics of the 818 :ref:`pymalloc memory allocator <pymalloc>` every time a new pymalloc object 819 arena is created, and on shutdown. 820 821 This variable is ignored if the :envvar:`PYTHONMALLOC` environment variable 822 is used to force the :c:func:`malloc` allocator of the C library, or if 823 Python is configured without ``pymalloc`` support. 824 825 .. versionchanged:: 3.6 826 This variable can now also be used on Python compiled in release mode. 827 It now has no effect if set to an empty string. 828 829 830.. envvar:: PYTHONLEGACYWINDOWSFSENCODING 831 832 If set to a non-empty string, the default :term:`filesystem encoding and 833 error handler` mode will revert to their pre-3.6 values of 'mbcs' and 834 'replace', respectively. Otherwise, the new defaults 'utf-8' and 835 'surrogatepass' are used. 836 837 This may also be enabled at runtime with 838 :func:`sys._enablelegacywindowsfsencoding()`. 839 840 .. availability:: Windows. 841 842 .. versionadded:: 3.6 843 See :pep:`529` for more details. 844 845.. envvar:: PYTHONLEGACYWINDOWSSTDIO 846 847 If set to a non-empty string, does not use the new console reader and 848 writer. This means that Unicode characters will be encoded according to 849 the active console code page, rather than using utf-8. 850 851 This variable is ignored if the standard streams are redirected (to files 852 or pipes) rather than referring to console buffers. 853 854 .. availability:: Windows. 855 856 .. versionadded:: 3.6 857 858 859.. envvar:: PYTHONCOERCECLOCALE 860 861 If set to the value ``0``, causes the main Python command line application 862 to skip coercing the legacy ASCII-based C and POSIX locales to a more 863 capable UTF-8 based alternative. 864 865 If this variable is *not* set (or is set to a value other than ``0``), the 866 ``LC_ALL`` locale override environment variable is also not set, and the 867 current locale reported for the ``LC_CTYPE`` category is either the default 868 ``C`` locale, or else the explicitly ASCII-based ``POSIX`` locale, then the 869 Python CLI will attempt to configure the following locales for the 870 ``LC_CTYPE`` category in the order listed before loading the interpreter 871 runtime: 872 873 * ``C.UTF-8`` 874 * ``C.utf8`` 875 * ``UTF-8`` 876 877 If setting one of these locale categories succeeds, then the ``LC_CTYPE`` 878 environment variable will also be set accordingly in the current process 879 environment before the Python runtime is initialized. This ensures that in 880 addition to being seen by both the interpreter itself and other locale-aware 881 components running in the same process (such as the GNU ``readline`` 882 library), the updated setting is also seen in subprocesses (regardless of 883 whether or not those processes are running a Python interpreter), as well as 884 in operations that query the environment rather than the current C locale 885 (such as Python's own :func:`locale.getdefaultlocale`). 886 887 Configuring one of these locales (either explicitly or via the above 888 implicit locale coercion) automatically enables the ``surrogateescape`` 889 :ref:`error handler <error-handlers>` for :data:`sys.stdin` and 890 :data:`sys.stdout` (:data:`sys.stderr` continues to use ``backslashreplace`` 891 as it does in any other locale). This stream handling behavior can be 892 overridden using :envvar:`PYTHONIOENCODING` as usual. 893 894 For debugging purposes, setting ``PYTHONCOERCECLOCALE=warn`` will cause 895 Python to emit warning messages on ``stderr`` if either the locale coercion 896 activates, or else if a locale that *would* have triggered coercion is 897 still active when the Python runtime is initialized. 898 899 Also note that even when locale coercion is disabled, or when it fails to 900 find a suitable target locale, :envvar:`PYTHONUTF8` will still activate by 901 default in legacy ASCII-based locales. Both features must be disabled in 902 order to force the interpreter to use ``ASCII`` instead of ``UTF-8`` for 903 system interfaces. 904 905 .. availability:: \*nix. 906 907 .. versionadded:: 3.7 908 See :pep:`538` for more details. 909 910 911.. envvar:: PYTHONDEVMODE 912 913 If this environment variable is set to a non-empty string, enable 914 :ref:`Python Development Mode <devmode>`, introducing additional runtime 915 checks that are too expensive to be enabled by default. 916 917 .. versionadded:: 3.7 918 919.. envvar:: PYTHONUTF8 920 921 If set to ``1``, enable the :ref:`Python UTF-8 Mode <utf8-mode>`. 922 923 If set to ``0``, disable the :ref:`Python UTF-8 Mode <utf8-mode>`. 924 925 Setting any other non-empty string causes an error during interpreter 926 initialisation. 927 928 .. versionadded:: 3.7 929 930.. envvar:: PYTHONWARNDEFAULTENCODING 931 932 If this environment variable is set to a non-empty string, issue a 933 :class:`EncodingWarning` when the locale-specific default encoding is used. 934 935 See :ref:`io-encoding-warning` for details. 936 937 .. versionadded:: 3.10 938 939 940Debug-mode variables 941~~~~~~~~~~~~~~~~~~~~ 942 943.. envvar:: PYTHONTHREADDEBUG 944 945 If set, Python will print threading debug info into stdout. 946 947 Need a :ref:`debug build of Python <debug-build>`. 948 949 .. deprecated-removed:: 3.10 3.12 950 951 952.. envvar:: PYTHONDUMPREFS 953 954 If set, Python will dump objects and reference counts still alive after 955 shutting down the interpreter. 956 957 Need Python configured with the :option:`--with-trace-refs` build option. 958