Berker Peksag | 8b1cbd2 | 2014-12-10 01:47:02 +0200 | [diff] [blame] | 1 | .. highlightlang:: 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 | |
| 181 | Print the Python version number and exit. Example output could be:: |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 182 | |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 183 | Python 3.0 |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 184 | |
| 185 | |
Christian Heimes | ad73a9c | 2013-08-10 16:36:18 +0200 | [diff] [blame] | 186 | .. _using-on-misc-options: |
| 187 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 188 | Miscellaneous options |
| 189 | ~~~~~~~~~~~~~~~~~~~~~ |
| 190 | |
Christian Heimes | 226679a | 2007-12-07 11:52:55 +0000 | [diff] [blame] | 191 | .. cmdoption:: -b |
| 192 | |
Serhiy Storchaka | 1dd4982 | 2015-03-20 16:54:57 +0200 | [diff] [blame] | 193 | Issue a warning when comparing :class:`bytes` or :class:`bytearray` with |
| 194 | :class:`str` or :class:`bytes` with :class:`int`. Issue an error when the |
Christian Heimes | 226679a | 2007-12-07 11:52:55 +0000 | [diff] [blame] | 195 | option is given twice (:option:`-bb`). |
| 196 | |
Serhiy Storchaka | 1dd4982 | 2015-03-20 16:54:57 +0200 | [diff] [blame] | 197 | .. versionchanged: 3.5 |
| 198 | Affects comparisons of :class:`bytes` with :class:`int`. |
Christian Heimes | 226679a | 2007-12-07 11:52:55 +0000 | [diff] [blame] | 199 | |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 200 | .. cmdoption:: -B |
| 201 | |
Larry Hastings | 770ce20 | 2015-04-19 13:50:12 -0700 | [diff] [blame] | 202 | If given, Python won't try to write ``.pyc`` files on the |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 203 | import of source modules. See also :envvar:`PYTHONDONTWRITEBYTECODE`. |
| 204 | |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 205 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 206 | .. cmdoption:: -d |
| 207 | |
| 208 | Turn on parser debugging output (for wizards only, depending on compilation |
| 209 | options). See also :envvar:`PYTHONDEBUG`. |
| 210 | |
| 211 | |
| 212 | .. cmdoption:: -E |
| 213 | |
| 214 | Ignore all :envvar:`PYTHON*` environment variables, e.g. |
| 215 | :envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set. |
| 216 | |
| 217 | |
| 218 | .. cmdoption:: -i |
| 219 | |
| 220 | When a script is passed as first argument or the :option:`-c` option is used, |
| 221 | enter interactive mode after executing the script or the command, even when |
| 222 | :data:`sys.stdin` does not appear to be a terminal. The |
| 223 | :envvar:`PYTHONSTARTUP` file is not read. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 224 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 225 | This can be useful to inspect global variables or a stack trace when a script |
| 226 | raises an exception. See also :envvar:`PYTHONINSPECT`. |
| 227 | |
| 228 | |
Christian Heimes | ad73a9c | 2013-08-10 16:36:18 +0200 | [diff] [blame] | 229 | .. cmdoption:: -I |
| 230 | |
| 231 | Run Python in isolated mode. This also implies -E and -s. |
| 232 | In isolated mode :data:`sys.path` contains neither the script's directory nor |
| 233 | the user's site-packages directory. All :envvar:`PYTHON*` environment |
| 234 | variables are ignored, too. Further restrictions may be imposed to prevent |
| 235 | the user from injecting malicious code. |
| 236 | |
| 237 | .. versionadded:: 3.4 |
| 238 | |
| 239 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 240 | .. cmdoption:: -O |
| 241 | |
| 242 | Turn on basic optimizations. This changes the filename extension for |
| 243 | compiled (:term:`bytecode`) files from ``.pyc`` to ``.pyo``. See also |
| 244 | :envvar:`PYTHONOPTIMIZE`. |
| 245 | |
| 246 | |
| 247 | .. cmdoption:: -OO |
| 248 | |
| 249 | Discard docstrings in addition to the :option:`-O` optimizations. |
| 250 | |
| 251 | |
Georg Brandl | 9d87119 | 2010-12-04 10:47:18 +0000 | [diff] [blame] | 252 | .. cmdoption:: -q |
| 253 | |
| 254 | Don't display the copyright and version messages even in interactive mode. |
| 255 | |
| 256 | .. versionadded:: 3.2 |
| 257 | |
| 258 | |
Georg Brandl | 2daf6ae | 2012-02-20 19:54:16 +0100 | [diff] [blame] | 259 | .. cmdoption:: -R |
| 260 | |
Antoine Pitrou | 0209dc1 | 2012-08-01 14:53:16 +0200 | [diff] [blame] | 261 | Kept for compatibility. On Python 3.3 and greater, hash randomization is |
| 262 | turned on by default. |
Georg Brandl | 2daf6ae | 2012-02-20 19:54:16 +0100 | [diff] [blame] | 263 | |
Antoine Pitrou | 0209dc1 | 2012-08-01 14:53:16 +0200 | [diff] [blame] | 264 | On previous versions of Python, this option turns on hash randomization, |
| 265 | so that the :meth:`__hash__` values of str, bytes and datetime |
| 266 | are "salted" with an unpredictable random value. Although they remain |
| 267 | constant within an individual Python process, they are not predictable |
| 268 | between repeated invocations of Python. |
| 269 | |
| 270 | Hash randomization is intended to provide protection against a |
| 271 | denial-of-service caused by carefully-chosen inputs that exploit the worst |
| 272 | case performance of a dict construction, O(n^2) complexity. See |
Georg Brandl | 2daf6ae | 2012-02-20 19:54:16 +0100 | [diff] [blame] | 273 | http://www.ocert.org/advisories/ocert-2011-003.html for details. |
| 274 | |
Antoine Pitrou | 0209dc1 | 2012-08-01 14:53:16 +0200 | [diff] [blame] | 275 | :envvar:`PYTHONHASHSEED` allows you to set a fixed value for the hash |
| 276 | seed secret. |
Georg Brandl | 2daf6ae | 2012-02-20 19:54:16 +0100 | [diff] [blame] | 277 | |
Georg Brandl | 09a7c72 | 2012-02-20 21:31:46 +0100 | [diff] [blame] | 278 | .. versionadded:: 3.2.3 |
Georg Brandl | 2daf6ae | 2012-02-20 19:54:16 +0100 | [diff] [blame] | 279 | |
| 280 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 281 | .. cmdoption:: -s |
| 282 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 283 | Don't add the :data:`user site-packages directory <site.USER_SITE>` to |
| 284 | :data:`sys.path`. |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 285 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 286 | .. seealso:: |
| 287 | |
| 288 | :pep:`370` -- Per user site-packages directory |
| 289 | |
| 290 | |
| 291 | .. cmdoption:: -S |
| 292 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 293 | Disable the import of the module :mod:`site` and the site-dependent |
Éric Araujo | c09fca6 | 2011-03-23 02:06:24 +0100 | [diff] [blame] | 294 | manipulations of :data:`sys.path` that it entails. Also disable these |
| 295 | manipulations if :mod:`site` is explicitly imported later (call |
| 296 | :func:`site.main` if you want them to be triggered). |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 297 | |
| 298 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 299 | .. cmdoption:: -u |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 300 | |
Ezio Melotti | 61b0c67 | 2013-07-25 05:04:02 +0200 | [diff] [blame] | 301 | Force the binary layer of the stdout and stderr streams (which is |
| 302 | available as their ``buffer`` attribute) to be unbuffered. The text I/O |
Antoine Pitrou | 08c08eb | 2011-12-21 11:24:15 +0100 | [diff] [blame] | 303 | layer will still be line-buffered if writing to the console, or |
| 304 | block-buffered if redirected to a non-interactive file. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 305 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 306 | See also :envvar:`PYTHONUNBUFFERED`. |
| 307 | |
| 308 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 309 | .. cmdoption:: -v |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 310 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 311 | Print a message each time a module is initialized, showing the place |
| 312 | (filename or built-in module) from which it is loaded. When given twice |
| 313 | (:option:`-vv`), print a message for each file that is checked for when |
| 314 | searching for a module. Also provides information on module cleanup at exit. |
| 315 | See also :envvar:`PYTHONVERBOSE`. |
| 316 | |
| 317 | |
| 318 | .. cmdoption:: -W arg |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 319 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 320 | Warning control. Python's warning machinery by default prints warning |
| 321 | messages to :data:`sys.stderr`. A typical warning message has the following |
| 322 | form:: |
| 323 | |
| 324 | file:line: category: message |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 325 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 326 | By default, each warning is printed once for each source line where it |
| 327 | occurs. This option controls how often warnings are printed. |
| 328 | |
| 329 | Multiple :option:`-W` options may be given; when a warning matches more than |
| 330 | one option, the action for the last matching option is performed. Invalid |
| 331 | :option:`-W` options are ignored (though, a warning message is printed about |
| 332 | invalid options when the first warning is issued). |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 333 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 334 | Warnings can also be controlled from within a Python program using the |
| 335 | :mod:`warnings` module. |
| 336 | |
| 337 | The simplest form of argument is one of the following action strings (or a |
| 338 | unique abbreviation): |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 339 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 340 | ``ignore`` |
| 341 | Ignore all warnings. |
| 342 | ``default`` |
| 343 | Explicitly request the default behavior (printing each warning once per |
| 344 | source line). |
| 345 | ``all`` |
| 346 | Print a warning each time it occurs (this may generate many messages if a |
| 347 | warning is triggered repeatedly for the same source line, such as inside a |
| 348 | loop). |
| 349 | ``module`` |
Georg Brandl | eeb575f | 2009-06-24 06:42:05 +0000 | [diff] [blame] | 350 | Print each warning only the first time it occurs in each module. |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 351 | ``once`` |
| 352 | Print each warning only the first time it occurs in the program. |
| 353 | ``error`` |
| 354 | Raise an exception instead of printing a warning message. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 355 | |
| 356 | The full form of argument is:: |
| 357 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 358 | action:message:category:module:line |
| 359 | |
| 360 | Here, *action* is as explained above but only applies to messages that match |
| 361 | the remaining fields. Empty fields match all values; trailing empty fields |
| 362 | may be omitted. The *message* field matches the start of the warning message |
| 363 | printed; this match is case-insensitive. The *category* field matches the |
Benjamin Peterson | 08bf91c | 2010-04-11 16:12:57 +0000 | [diff] [blame] | 364 | warning category. This must be a class name; the match tests whether the |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 365 | actual warning category of the message is a subclass of the specified warning |
| 366 | category. The full class name must be given. The *module* field matches the |
| 367 | (fully-qualified) module name; this match is case-sensitive. The *line* |
| 368 | field matches the line number, where zero matches all line numbers and is |
| 369 | thus equivalent to an omitted line number. |
| 370 | |
| 371 | .. seealso:: |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 372 | :mod:`warnings` -- the warnings module |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 373 | |
| 374 | :pep:`230` -- Warning framework |
| 375 | |
Philip Jenvey | 0805ca3 | 2010-04-07 04:04:10 +0000 | [diff] [blame] | 376 | :envvar:`PYTHONWARNINGS` |
| 377 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 378 | |
| 379 | .. cmdoption:: -x |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 380 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 381 | Skip the first line of the source, allowing use of non-Unix forms of |
| 382 | ``#!cmd``. This is intended for a DOS specific hack only. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 383 | |
Georg Brandl | 3221dc9 | 2009-04-27 16:23:47 +0000 | [diff] [blame] | 384 | .. note:: The line numbers in error messages will be off by one. |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 385 | |
Antoine Pitrou | 9583cac | 2010-10-21 13:42:28 +0000 | [diff] [blame] | 386 | |
| 387 | .. cmdoption:: -X |
| 388 | |
| 389 | Reserved for various implementation-specific options. CPython currently |
Victor Stinner | ed3b0bc | 2013-11-23 12:27:24 +0100 | [diff] [blame] | 390 | defines the following possible values: |
Ezio Melotti | 1f8898a | 2013-03-26 01:59:56 +0200 | [diff] [blame] | 391 | |
Ezio Melotti | 711c370 | 2013-03-26 02:38:40 +0200 | [diff] [blame] | 392 | * ``-X faulthandler`` to enable :mod:`faulthandler`; |
Ezio Melotti | 1f8898a | 2013-03-26 01:59:56 +0200 | [diff] [blame] | 393 | * ``-X showrefcount`` to enable the output of the total reference count |
| 394 | and memory blocks (only works on debug builds); |
Victor Stinner | 3728d6c | 2013-11-23 12:37:20 +0100 | [diff] [blame] | 395 | * ``-X tracemalloc`` to start tracing Python memory allocations using the |
| 396 | :mod:`tracemalloc` module. By default, only the most recent frame is |
| 397 | stored in a traceback of a trace. Use ``-X tracemalloc=NFRAME`` to start |
| 398 | tracing with a traceback limit of *NFRAME* frames. See the |
| 399 | :func:`tracemalloc.start` for more information. |
Ezio Melotti | 1f8898a | 2013-03-26 01:59:56 +0200 | [diff] [blame] | 400 | |
Martin Panter | c04fb56 | 2016-02-10 05:44:01 +0000 | [diff] [blame^] | 401 | It also allows passing arbitrary values and retrieving them through the |
Ezio Melotti | 1f8898a | 2013-03-26 01:59:56 +0200 | [diff] [blame] | 402 | :data:`sys._xoptions` dictionary. |
Antoine Pitrou | 9583cac | 2010-10-21 13:42:28 +0000 | [diff] [blame] | 403 | |
| 404 | .. versionchanged:: 3.2 |
| 405 | It is now allowed to pass :option:`-X` with CPython. |
| 406 | |
Ezio Melotti | a1eb483 | 2013-03-26 02:36:28 +0200 | [diff] [blame] | 407 | .. versionadded:: 3.3 |
| 408 | The ``-X faulthandler`` option. |
| 409 | |
Ezio Melotti | 1f8898a | 2013-03-26 01:59:56 +0200 | [diff] [blame] | 410 | .. versionadded:: 3.4 |
Victor Stinner | ed3b0bc | 2013-11-23 12:27:24 +0100 | [diff] [blame] | 411 | The ``-X showrefcount`` and ``-X tracemalloc`` options. |
Ezio Melotti | 1f8898a | 2013-03-26 01:59:56 +0200 | [diff] [blame] | 412 | |
Antoine Pitrou | 9583cac | 2010-10-21 13:42:28 +0000 | [diff] [blame] | 413 | |
Barry Warsaw | 615368f | 2010-02-05 19:12:30 +0000 | [diff] [blame] | 414 | Options you shouldn't use |
| 415 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 416 | |
| 417 | .. cmdoption:: -J |
| 418 | |
| 419 | Reserved for use by Jython_. |
| 420 | |
Georg Brandl | 525d355 | 2014-10-29 10:26:56 +0100 | [diff] [blame] | 421 | .. _Jython: http://www.jython.org/ |
Barry Warsaw | 615368f | 2010-02-05 19:12:30 +0000 | [diff] [blame] | 422 | |
Georg Brandl | 2daf6ae | 2012-02-20 19:54:16 +0100 | [diff] [blame] | 423 | |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 424 | .. _using-on-envvars: |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 425 | |
| 426 | Environment variables |
| 427 | --------------------- |
| 428 | |
Andrew Svetlov | abfc7df | 2012-10-17 17:15:43 +0300 | [diff] [blame] | 429 | These environment variables influence Python's behavior, they are processed |
Christian Heimes | ad73a9c | 2013-08-10 16:36:18 +0200 | [diff] [blame] | 430 | 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] | 431 | command-line switches override environmental variables where there is a |
| 432 | conflict. |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 433 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 434 | .. envvar:: PYTHONHOME |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 435 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 436 | Change the location of the standard Python libraries. By default, the |
Christian Heimes | e1c9811 | 2008-01-21 11:20:28 +0000 | [diff] [blame] | 437 | libraries are searched in :file:`{prefix}/lib/python{version}` and |
| 438 | :file:`{exec_prefix}/lib/python{version}`, where :file:`{prefix}` and |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 439 | :file:`{exec_prefix}` are installation-dependent directories, both defaulting |
| 440 | to :file:`/usr/local`. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 441 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 442 | When :envvar:`PYTHONHOME` is set to a single directory, its value replaces |
| 443 | both :file:`{prefix}` and :file:`{exec_prefix}`. To specify different values |
Christian Heimes | e1c9811 | 2008-01-21 11:20:28 +0000 | [diff] [blame] | 444 | for these, set :envvar:`PYTHONHOME` to :file:`{prefix}:{exec_prefix}`. |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 445 | |
| 446 | |
| 447 | .. envvar:: PYTHONPATH |
| 448 | |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 449 | 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] | 450 | the shell's :envvar:`PATH`: one or more directory pathnames separated by |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 451 | :data:`os.pathsep` (e.g. colons on Unix or semicolons on Windows). |
| 452 | Non-existent directories are silently ignored. |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 453 | |
| 454 | In addition to normal directories, individual :envvar:`PYTHONPATH` entries |
| 455 | may refer to zipfiles containing pure Python modules (in either source or |
| 456 | compiled form). Extension modules cannot be imported from zipfiles. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 457 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 458 | The default search path is installation dependent, but generally begins with |
Georg Brandl | 1f01deb | 2009-01-03 22:47:39 +0000 | [diff] [blame] | 459 | :file:`{prefix}/lib/python{version}` (see :envvar:`PYTHONHOME` above). It |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 460 | is *always* appended to :envvar:`PYTHONPATH`. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 461 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 462 | An additional directory will be inserted in the search path in front of |
| 463 | :envvar:`PYTHONPATH` as described above under |
| 464 | :ref:`using-on-interface-options`. The search path can be manipulated from |
| 465 | within a Python program as the variable :data:`sys.path`. |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 466 | |
| 467 | |
| 468 | .. envvar:: PYTHONSTARTUP |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 469 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 470 | If this is the name of a readable file, the Python commands in that file are |
| 471 | executed before the first prompt is displayed in interactive mode. The file |
| 472 | is executed in the same namespace where interactive commands are executed so |
| 473 | that objects defined or imported in it can be used without qualification in |
| 474 | 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] | 475 | :data:`sys.ps2` and the hook :data:`sys.__interactivehook__` in this file. |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 476 | |
| 477 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 478 | .. envvar:: PYTHONOPTIMIZE |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 479 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 480 | If this is set to a non-empty string it is equivalent to specifying the |
| 481 | :option:`-O` option. If set to an integer, it is equivalent to specifying |
| 482 | :option:`-O` multiple times. |
| 483 | |
| 484 | |
| 485 | .. envvar:: PYTHONDEBUG |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 486 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 487 | If this is set to a non-empty string it is equivalent to specifying the |
| 488 | :option:`-d` option. If set to an integer, it is equivalent to specifying |
| 489 | :option:`-d` multiple times. |
| 490 | |
| 491 | |
| 492 | .. envvar:: PYTHONINSPECT |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 493 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 494 | If this is set to a non-empty string it is equivalent to specifying the |
| 495 | :option:`-i` option. |
| 496 | |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 497 | This variable can also be modified by Python code using :data:`os.environ` |
| 498 | to force inspect mode on program termination. |
| 499 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 500 | |
| 501 | .. envvar:: PYTHONUNBUFFERED |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 502 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 503 | If this is set to a non-empty string it is equivalent to specifying the |
| 504 | :option:`-u` option. |
| 505 | |
| 506 | |
| 507 | .. envvar:: PYTHONVERBOSE |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 508 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 509 | If this is set to a non-empty string it is equivalent to specifying the |
| 510 | :option:`-v` option. If set to an integer, it is equivalent to specifying |
| 511 | :option:`-v` multiple times. |
| 512 | |
| 513 | |
| 514 | .. envvar:: PYTHONCASEOK |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 515 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 516 | If this is set, Python ignores case in :keyword:`import` statements. This |
Brett Cannon | fc70cbc | 2012-01-26 18:30:52 -0500 | [diff] [blame] | 517 | only works on Windows and OS X. |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 518 | |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 519 | |
| 520 | .. envvar:: PYTHONDONTWRITEBYTECODE |
| 521 | |
Victor Stinner | 8898350 | 2013-09-08 11:36:23 +0200 | [diff] [blame] | 522 | If this is set to a non-empty string, Python won't try to write ``.pyc`` or |
| 523 | ``.pyo`` files on the import of source modules. This is equivalent to |
| 524 | specifying the :option:`-B` option. |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 525 | |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 526 | |
Georg Brandl | 2daf6ae | 2012-02-20 19:54:16 +0100 | [diff] [blame] | 527 | .. envvar:: PYTHONHASHSEED |
| 528 | |
Antoine Pitrou | 0209dc1 | 2012-08-01 14:53:16 +0200 | [diff] [blame] | 529 | If this variable is not set or set to ``random``, a random value is used |
| 530 | to seed the hashes of str, bytes and datetime objects. |
Georg Brandl | 2daf6ae | 2012-02-20 19:54:16 +0100 | [diff] [blame] | 531 | |
| 532 | If :envvar:`PYTHONHASHSEED` is set to an integer value, it is used as a fixed |
| 533 | seed for generating the hash() of the types covered by the hash |
| 534 | randomization. |
| 535 | |
| 536 | Its purpose is to allow repeatable hashing, such as for selftests for the |
| 537 | interpreter itself, or to allow a cluster of python processes to share hash |
| 538 | values. |
| 539 | |
| 540 | 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] | 541 | the value 0 will disable hash randomization. |
Georg Brandl | 2daf6ae | 2012-02-20 19:54:16 +0100 | [diff] [blame] | 542 | |
Georg Brandl | 09a7c72 | 2012-02-20 21:31:46 +0100 | [diff] [blame] | 543 | .. versionadded:: 3.2.3 |
Georg Brandl | 2daf6ae | 2012-02-20 19:54:16 +0100 | [diff] [blame] | 544 | |
| 545 | |
Georg Brandl | 2c906f1 | 2008-06-11 18:03:09 +0000 | [diff] [blame] | 546 | .. envvar:: PYTHONIOENCODING |
| 547 | |
Éric Araujo | 358b63a | 2010-08-18 22:35:23 +0000 | [diff] [blame] | 548 | 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] | 549 | for stdin/stdout/stderr, in the syntax ``encodingname:errorhandler``. Both |
| 550 | the ``encodingname`` and the ``:errorhandler`` parts are optional and have |
| 551 | the same meaning as in :func:`str.encode`. |
Georg Brandl | 2c906f1 | 2008-06-11 18:03:09 +0000 | [diff] [blame] | 552 | |
Georg Brandl | 559e5d7 | 2008-06-11 18:37:52 +0000 | [diff] [blame] | 553 | For stderr, the ``:errorhandler`` part is ignored; the handler will always be |
| 554 | ``'backslashreplace'``. |
| 555 | |
Serhiy Storchaka | bf28d2d | 2013-09-13 11:46:24 +0300 | [diff] [blame] | 556 | .. versionchanged:: 3.4 |
| 557 | The ``encodingname`` part is now optional. |
| 558 | |
Georg Brandl | 2c906f1 | 2008-06-11 18:03:09 +0000 | [diff] [blame] | 559 | |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 560 | .. envvar:: PYTHONNOUSERSITE |
| 561 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 562 | If this is set, Python won't add the :data:`user site-packages directory |
| 563 | <site.USER_SITE>` to :data:`sys.path`. |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 564 | |
| 565 | .. seealso:: |
| 566 | |
| 567 | :pep:`370` -- Per user site-packages directory |
| 568 | |
| 569 | |
| 570 | .. envvar:: PYTHONUSERBASE |
| 571 | |
Éric Araujo | de4f05b | 2011-08-06 01:51:07 +0200 | [diff] [blame] | 572 | Defines the :data:`user base directory <site.USER_BASE>`, which is used to |
| 573 | 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] | 574 | and :ref:`Distutils installation paths <inst-alt-install-user>` for |
| 575 | ``python setup.py install --user``. |
Christian Heimes | 8dc226f | 2008-05-06 23:45:46 +0000 | [diff] [blame] | 576 | |
| 577 | .. seealso:: |
| 578 | |
| 579 | :pep:`370` -- Per user site-packages directory |
| 580 | |
| 581 | |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 582 | .. envvar:: PYTHONEXECUTABLE |
| 583 | |
| 584 | If this environment variable is set, ``sys.argv[0]`` will be set to its |
| 585 | 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] | 586 | Mac OS X. |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 587 | |
Philip Jenvey | 0805ca3 | 2010-04-07 04:04:10 +0000 | [diff] [blame] | 588 | .. envvar:: PYTHONWARNINGS |
| 589 | |
Benjamin Peterson | 08bf91c | 2010-04-11 16:12:57 +0000 | [diff] [blame] | 590 | 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] | 591 | separated string, it is equivalent to specifying :option:`-W` multiple |
| 592 | times. |
| 593 | |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 594 | .. envvar:: PYTHONFAULTHANDLER |
| 595 | |
Victor Stinner | 8898350 | 2013-09-08 11:36:23 +0200 | [diff] [blame] | 596 | If this environment variable is set to a non-empty string, |
| 597 | :func:`faulthandler.enable` is called at startup: install a handler for |
| 598 | :const:`SIGSEGV`, :const:`SIGFPE`, :const:`SIGABRT`, :const:`SIGBUS` and |
| 599 | :const:`SIGILL` signals to dump the Python traceback. This is equivalent to |
| 600 | :option:`-X` ``faulthandler`` option. |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 601 | |
Victor Stinner | ae6d05b | 2013-07-28 02:56:50 +0200 | [diff] [blame] | 602 | .. versionadded:: 3.3 |
| 603 | |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 604 | |
Victor Stinner | ed3b0bc | 2013-11-23 12:27:24 +0100 | [diff] [blame] | 605 | .. envvar:: PYTHONTRACEMALLOC |
| 606 | |
Victor Stinner | 3728d6c | 2013-11-23 12:37:20 +0100 | [diff] [blame] | 607 | If this environment variable is set to a non-empty string, start tracing |
| 608 | Python memory allocations using the :mod:`tracemalloc` module. The value of |
| 609 | the variable is the maximum number of frames stored in a traceback of a |
| 610 | trace. For example, ``PYTHONTRACEMALLOC=1`` stores only the most recent |
| 611 | frame. See the :func:`tracemalloc.start` for more information. |
Victor Stinner | ed3b0bc | 2013-11-23 12:27:24 +0100 | [diff] [blame] | 612 | |
| 613 | .. versionadded:: 3.4 |
| 614 | |
| 615 | |
Victor Stinner | 0f3e6bc | 2014-02-19 23:15:02 +0100 | [diff] [blame] | 616 | .. envvar:: PYTHONASYNCIODEBUG |
| 617 | |
Victor Stinner | 62511fd | 2014-06-23 00:36:11 +0200 | [diff] [blame] | 618 | If this environment variable is set to a non-empty string, enable the |
| 619 | :ref:`debug mode <asyncio-debug-mode>` of the :mod:`asyncio` module. |
Victor Stinner | 0f3e6bc | 2014-02-19 23:15:02 +0100 | [diff] [blame] | 620 | |
| 621 | .. versionadded:: 3.4 |
| 622 | |
| 623 | |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 624 | Debug-mode variables |
| 625 | ~~~~~~~~~~~~~~~~~~~~ |
| 626 | |
| 627 | Setting these variables only has an effect in a debug build of Python, that is, |
Éric Araujo | d2f8cec | 2011-06-08 05:29:39 +0200 | [diff] [blame] | 628 | if Python was configured with the ``--with-pydebug`` build option. |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 629 | |
| 630 | .. envvar:: PYTHONTHREADDEBUG |
| 631 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 632 | If set, Python will print threading debug info. |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 633 | |
Christian Heimes | 790c823 | 2008-01-07 21:14:23 +0000 | [diff] [blame] | 634 | |
| 635 | .. envvar:: PYTHONDUMPREFS |
| 636 | |
| 637 | If set, Python will dump objects and reference counts still alive after |
| 638 | shutting down the interpreter. |
| 639 | |
| 640 | |
| 641 | .. envvar:: PYTHONMALLOCSTATS |
| 642 | |
| 643 | If set, Python will print memory allocation statistics every time a new |
| 644 | object arena is created, and on shutdown. |