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