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