1 .. highlightlang:: none
3 .. ATTENTION: You probably should update Misc/python.man, too, if you modify
8 Command line and environment
9 ============================
11 The CPython interpreter scans the command line and the environment for various
16 Other implementations' command line schemes may differ. See
17 :ref:`implementations` for further resources.
25 When invoking Python, you may specify any of these options::
27 python [-BdEiOQsStuUvVWxX3?] [-c command | -m module-name | script | - ] [args]
29 The most common use case is, of course, a simple invocation of a script::
34 .. _using-on-interface-options:
39 The interpreter interface resembles that of the UNIX shell, but provides some
40 additional methods of invocation:
42 * When called with standard input connected to a tty device, it prompts for
43 commands and executes them until an EOF (an end-of-file character, you can
44 produce that with *Ctrl-D* on UNIX or *Ctrl-Z, Enter* on Windows) is read.
45 * When called with a file name argument or with a file as standard input, it
46 reads and executes a script from that file.
47 * When called with a directory name argument, it reads and executes an
48 appropriately named script from that directory.
49 * When called with ``-c command``, it executes the Python statement(s) given as
50 *command*. Here *command* may contain multiple statements separated by
51 newlines. Leading whitespace is significant in Python statements!
52 * When called with ``-m module-name``, the given module is located on the
53 Python module path and executed as a script.
55 In non-interactive mode, the entire input is parsed before it is executed.
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
62 .. cmdoption:: -c <command>
64 Execute the Python code in *command*. *command* can be one or more
65 statements separated by newlines, with significant leading whitespace as in
68 If this option is given, the first element of :data:`sys.argv` will be
69 ``"-c"`` and the current directory will be added to the start of
70 :data:`sys.path` (allowing modules in that directory to be imported as top
74 .. cmdoption:: -m <module-name>
76 Search :data:`sys.path` for the named module and execute its contents as
77 the :mod:`__main__` module.
79 Since the argument is a *module* name, you must not give a file extension
80 (``.py``). The ``module-name`` should be a valid Python module name, but
81 the implementation may not always enforce this (e.g. it may allow you to
82 use a name that includes a hyphen).
84 Package names are also permitted. When a package name is supplied instead
85 of a normal module, the interpreter will execute ``<pkg>.__main__`` as
86 the main module. This behaviour is deliberately similar to the handling
87 of directories and zipfiles that are passed to the interpreter as the
92 This option cannot be used with built-in modules and extension modules
93 written in C, since they do not have Python module files. However, it
94 can still be used for precompiled modules, even if the original source
95 file is not available.
97 If this option is given, the first element of :data:`sys.argv` will be the
98 full path to the module file. As with the :option:`-c` option, the current
99 directory will be added to the start of :data:`sys.path`.
101 Many standard library modules contain code that is invoked on their execution
102 as a script. An example is the :mod:`timeit` module::
104 python -mtimeit -s 'setup here' 'benchmarked code here'
105 python -mtimeit -h # for details
108 :func:`runpy.run_module`
109 Equivalent functionality directly available to Python code
111 :pep:`338` -- Executing modules as scripts
113 .. versionadded:: 2.4
115 .. versionchanged:: 2.5
116 The named module can now be located inside a package.
118 .. versionchanged:: 2.7
119 Supply the package name to run a ``__main__`` submodule.
120 sys.argv[0] is now set to ``"-m"`` while searching for the module
121 (it was previously incorrectly set to ``"-c"``)
126 Read commands from standard input (:data:`sys.stdin`). If standard input is
127 a terminal, :option:`-i` is implied.
129 If this option is given, the first element of :data:`sys.argv` will be
130 ``"-"`` and the current directory will be added to the start of
134 .. describe:: <script>
136 Execute the Python code contained in *script*, which must be a filesystem
137 path (absolute or relative) referring to either a Python file, a directory
138 containing a ``__main__.py`` file, or a zipfile containing a
139 ``__main__.py`` file.
141 If this option is given, the first element of :data:`sys.argv` will be the
142 script name as given on the command line.
144 If the script name refers directly to a Python file, the directory
145 containing that file is added to the start of :data:`sys.path`, and the
146 file is executed as the :mod:`__main__` module.
148 If the script name refers to a directory or zipfile, the script name is
149 added to the start of :data:`sys.path` and the ``__main__.py`` file in
150 that location is executed as the :mod:`__main__` module.
152 .. versionchanged:: 2.5
153 Directories and zipfiles containing a ``__main__.py`` file at the top
154 level are now considered valid Python scripts.
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
158 start of :data:`sys.path`.
160 .. seealso:: :ref:`tut-invoking`
170 Print a short description of all command line options.
172 .. versionchanged:: 2.5
173 The ``--help`` variant.
179 Print the Python version number and exit. Example output could be::
183 .. versionchanged:: 2.5
184 The ``--version`` variant.
187 Miscellaneous options
188 ~~~~~~~~~~~~~~~~~~~~~
192 If given, Python won't try to write ``.pyc`` or ``.pyo`` files on the
193 import of source modules. See also :envvar:`PYTHONDONTWRITEBYTECODE`.
195 .. versionadded:: 2.6
200 Turn on parser debugging output (for wizards only, depending on compilation
201 options). See also :envvar:`PYTHONDEBUG`.
206 Ignore all :envvar:`PYTHON*` environment variables, e.g.
207 :envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
209 .. versionadded:: 2.2
214 When a script is passed as first argument or the :option:`-c` option is used,
215 enter interactive mode after executing the script or the command, even when
216 :data:`sys.stdin` does not appear to be a terminal. The
217 :envvar:`PYTHONSTARTUP` file is not read.
219 This can be useful to inspect global variables or a stack trace when a script
220 raises an exception. See also :envvar:`PYTHONINSPECT`.
225 Turn on basic optimizations. This changes the filename extension for
226 compiled (:term:`bytecode`) files from ``.pyc`` to ``.pyo``. See also
227 :envvar:`PYTHONOPTIMIZE`.
232 Discard docstrings in addition to the :option:`-O` optimizations.
235 .. cmdoption:: -Q <arg>
237 Division control. The argument must be one of the following:
240 division of int/int and long/long return an int or long (*default*)
242 new division semantics, i.e. division of int/int and long/long returns a
245 old division semantics with a warning for int/int and long/long
247 old division semantics with a warning for all uses of the division operator
250 :file:`Tools/scripts/fixdiv.py`
251 for a use of ``warnall``
253 :pep:`238` -- Changing the division operator
258 Don't add user site directory to sys.path
260 .. versionadded:: 2.6
264 :pep:`370` -- Per user site-packages directory
269 Disable the import of the module :mod:`site` and the site-dependent
270 manipulations of :data:`sys.path` that it entails.
275 Issue a warning when a source file mixes tabs and spaces for indentation in a
276 way that makes it depend on the worth of a tab expressed in spaces. Issue an
277 error when the option is given twice (:option:`-tt`).
282 Force stdin, stdout and stderr to be totally unbuffered. On systems where it
283 matters, also put stdin, stdout and stderr in binary mode.
285 Note that there is internal buffering in :meth:`file.readlines` and
286 :ref:`bltin-file-objects` (``for line in sys.stdin``) which is not influenced
287 by this option. To work around this, you will want to use
288 :meth:`file.readline` inside a ``while 1:`` loop.
290 See also :envvar:`PYTHONUNBUFFERED`.
295 Print a message each time a module is initialized, showing the place
296 (filename or built-in module) from which it is loaded. When given twice
297 (:option:`-vv`), print a message for each file that is checked for when
298 searching for a module. Also provides information on module cleanup at exit.
299 See also :envvar:`PYTHONVERBOSE`.
302 .. cmdoption:: -W arg
304 Warning control. Python's warning machinery by default prints warning
305 messages to :data:`sys.stderr`. A typical warning message has the following
308 file:line: category: message
310 By default, each warning is printed once for each source line where it
311 occurs. This option controls how often warnings are printed.
313 Multiple :option:`-W` options may be given; when a warning matches more than
314 one option, the action for the last matching option is performed. Invalid
315 :option:`-W` options are ignored (though, a warning message is printed about
316 invalid options when the first warning is issued).
318 Starting from Python 2.7, :exc:`DeprecationWarning` and its descendants
319 are ignored by default. The :option:`-Wd` option can be used to re-enable
322 Warnings can also be controlled from within a Python program using the
323 :mod:`warnings` module.
325 The simplest form of argument is one of the following action strings (or a
326 unique abbreviation) by themselves:
331 Explicitly request the default behavior (printing each warning once per
334 Print a warning each time it occurs (this may generate many messages if a
335 warning is triggered repeatedly for the same source line, such as inside a
338 Print each warning only the first time it occurs in each module.
340 Print each warning only the first time it occurs in the program.
342 Raise an exception instead of printing a warning message.
344 The full form of argument is::
346 action:message:category:module:line
348 Here, *action* is as explained above but only applies to messages that match
349 the remaining fields. Empty fields match all values; trailing empty fields
350 may be omitted. The *message* field matches the start of the warning message
351 printed; this match is case-insensitive. The *category* field matches the
352 warning category. This must be a class name; the match tests whether the
353 actual warning category of the message is a subclass of the specified warning
354 category. The full class name must be given. The *module* field matches the
355 (fully-qualified) module name; this match is case-sensitive. The *line*
356 field matches the line number, where zero matches all line numbers and is
357 thus equivalent to an omitted line number.
360 :mod:`warnings` -- the warnings module
362 :pep:`230` -- Warning framework
364 :envvar:`PYTHONWARNINGS`
369 Skip the first line of the source, allowing use of non-Unix forms of
370 ``#!cmd``. This is intended for a DOS specific hack only.
372 .. note:: The line numbers in error messages will be off by one.
376 Warn about Python 3.x incompatibilities which cannot be fixed trivially by
377 :ref:`2to3 <2to3-reference>`. Among these are:
379 * :meth:`dict.has_key`
387 Using these will emit a :exc:`DeprecationWarning`.
389 .. versionadded:: 2.6
391 Options you shouldn't use
392 ~~~~~~~~~~~~~~~~~~~~~~~~~
396 Reserved for use by Jython_.
398 .. _Jython: http://jython.org
402 Turns all string literals into unicodes globally. Do not be tempted to use
403 this option as it will probably break your world. It also produces
404 ``.pyc`` files with a different magic number than normal. Instead, you can
405 enable unicode literals on a per-module basis by using::
407 from __future__ import unicode_literals
409 at the top of the file. See :mod:`__future__` for details.
413 Reserved for alternative implementations of Python to use for their own
416 .. _using-on-envvars:
418 Environment variables
419 ---------------------
421 These environment variables influence Python's behavior.
423 .. envvar:: PYTHONHOME
425 Change the location of the standard Python libraries. By default, the
426 libraries are searched in :file:`{prefix}/lib/python{version}` and
427 :file:`{exec_prefix}/lib/python{version}`, where :file:`{prefix}` and
428 :file:`{exec_prefix}` are installation-dependent directories, both defaulting
429 to :file:`/usr/local`.
431 When :envvar:`PYTHONHOME` is set to a single directory, its value replaces
432 both :file:`{prefix}` and :file:`{exec_prefix}`. To specify different values
433 for these, set :envvar:`PYTHONHOME` to :file:`{prefix}:{exec_prefix}`.
436 .. envvar:: PYTHONPATH
438 Augment the default search path for module files. The format is the same as
439 the shell's :envvar:`PATH`: one or more directory pathnames separated by
440 :data:`os.pathsep` (e.g. colons on Unix or semicolons on Windows).
441 Non-existent directories are silently ignored.
443 In addition to normal directories, individual :envvar:`PYTHONPATH` entries
444 may refer to zipfiles containing pure Python modules (in either source or
445 compiled form). Extension modules cannot be imported from zipfiles.
447 The default search path is installation dependent, but generally begins with
448 :file:`{prefix}/lib/python{version}` (see :envvar:`PYTHONHOME` above). It
449 is *always* appended to :envvar:`PYTHONPATH`.
451 An additional directory will be inserted in the search path in front of
452 :envvar:`PYTHONPATH` as described above under
453 :ref:`using-on-interface-options`. The search path can be manipulated from
454 within a Python program as the variable :data:`sys.path`.
457 .. envvar:: PYTHONSTARTUP
459 If this is the name of a readable file, the Python commands in that file are
460 executed before the first prompt is displayed in interactive mode. The file
461 is executed in the same namespace where interactive commands are executed so
462 that objects defined or imported in it can be used without qualification in
463 the interactive session. You can also change the prompts :data:`sys.ps1` and
464 :data:`sys.ps2` in this file.
467 .. envvar:: PYTHONY2K
469 Set this to a non-empty string to cause the :mod:`time` module to require
470 dates specified as strings to include 4-digit years, otherwise 2-digit years
471 are converted based on rules described in the :mod:`time` module
475 .. envvar:: PYTHONOPTIMIZE
477 If this is set to a non-empty string it is equivalent to specifying the
478 :option:`-O` option. If set to an integer, it is equivalent to specifying
479 :option:`-O` multiple times.
482 .. envvar:: PYTHONDEBUG
484 If this is set to a non-empty string it is equivalent to specifying the
485 :option:`-d` option. If set to an integer, it is equivalent to specifying
486 :option:`-d` multiple times.
489 .. envvar:: PYTHONINSPECT
491 If this is set to a non-empty string it is equivalent to specifying the
494 This variable can also be modified by Python code using :data:`os.environ`
495 to force inspect mode on program termination.
498 .. envvar:: PYTHONUNBUFFERED
500 If this is set to a non-empty string it is equivalent to specifying the
504 .. envvar:: PYTHONVERBOSE
506 If this is set to a non-empty string it is equivalent to specifying the
507 :option:`-v` option. If set to an integer, it is equivalent to specifying
508 :option:`-v` multiple times.
511 .. envvar:: PYTHONCASEOK
513 If this is set, Python ignores case in :keyword:`import` statements. This
514 only works on Windows.
517 .. envvar:: PYTHONDONTWRITEBYTECODE
519 If this is set, Python won't try to write ``.pyc`` or ``.pyo`` files on the
520 import of source modules.
522 .. versionadded:: 2.6
524 .. envvar:: PYTHONIOENCODING
526 Overrides the encoding used for stdin/stdout/stderr, in the syntax
527 ``encodingname:errorhandler``. The ``:errorhandler`` part is optional and
528 has the same meaning as in :func:`str.encode`.
530 .. versionadded:: 2.6
533 .. envvar:: PYTHONNOUSERSITE
535 If this is set, Python won't add the user site directory to sys.path
537 .. versionadded:: 2.6
541 :pep:`370` -- Per user site-packages directory
544 .. envvar:: PYTHONUSERBASE
546 Sets the base directory for the user site directory
548 .. versionadded:: 2.6
552 :pep:`370` -- Per user site-packages directory
555 .. envvar:: PYTHONEXECUTABLE
557 If this environment variable is set, ``sys.argv[0]`` will be set to its
558 value instead of the value got through the C runtime. Only works on
561 .. envvar:: PYTHONWARNINGS
563 This is equivalent to the :option:`-W` option. If set to a comma
564 separated string, it is equivalent to specifying :option:`-W` multiple
571 Setting these variables only has an effect in a debug build of Python, that is,
572 if Python was configured with the :option:`--with-pydebug` build option.
574 .. envvar:: PYTHONTHREADDEBUG
576 If set, Python will print threading debug info.
578 .. versionchanged:: 2.6
579 Previously, this variable was called ``THREADDEBUG``.
581 .. envvar:: PYTHONDUMPREFS
583 If set, Python will dump objects and reference counts still alive after
584 shutting down the interpreter.
587 .. envvar:: PYTHONMALLOCSTATS
589 If set, Python will print memory allocation statistics every time a new
590 object arena is created, and on shutdown.