1 .. highlightlang:: none
5 Command line and environment
6 ============================
8 The CPython interpreter scans the command line and the environment for various
13 Other implementations' command line schemes may differ. See
14 :ref:`implementations` for further resources.
22 When invoking Python, you may specify any of these options::
24 python [-dEiOQsStuUvxX3?] [-c command | -m module-name | script | - ] [args]
26 The most common use case is, of course, a simple invocation of a script::
31 .. _using-on-interface-options:
36 The interpreter interface resembles that of the UNIX shell, but provides some
37 additional methods of invocation:
39 * When called with standard input connected to a tty device, it prompts for
40 commands and executes them until an EOF (an end-of-file character, you can
41 produce that with *Ctrl-D* on UNIX or *Ctrl-Z, Enter* on Windows) is read.
42 * When called with a file name argument or with a file as standard input, it
43 reads and executes a script from that file.
44 * When called with a directory name argument, it reads and executes an
45 appropriately named script from that directory.
46 * When called with ``-c command``, it executes the Python statement(s) given as
47 *command*. Here *command* may contain multiple statements separated by
48 newlines. Leading whitespace is significant in Python statements!
49 * When called with ``-m module-name``, the given module is located on the
50 Python module path and executed as a script.
52 In non-interactive mode, the entire input is parsed before it is executed.
54 An interface option terminates the list of options consumed by the interpreter,
55 all consecutive arguments will end up in :data:`sys.argv` -- note that the first
56 element, subscript zero (``sys.argv[0]``), is a string reflecting the program's
59 .. cmdoption:: -c <command>
61 Execute the Python code in *command*. *command* can be one ore more
62 statements separated by newlines, with significant leading whitespace as in
65 If this option is given, the first element of :data:`sys.argv` will be
66 ``"-c"`` and the current directory will be added to the start of
67 :data:`sys.path` (allowing modules in that directory to be imported as top
71 .. cmdoption:: -m <module-name>
73 Search :data:`sys.path` for the named module and execute its contents as
74 the :mod:`__main__` module.
76 Since the argument is a *module* name, you must not give a file extension
77 (``.py``). The ``module-name`` should be a valid Python module name, but
78 the implementation may not always enforce this (e.g. it may allow you to
79 use a name that includes a hyphen).
81 Package names are also permitted. When a package name is supplied instead
82 of a normal module, the interpreter will execute ``<pkg>.__main__`` as
83 the main module. This behaviour is deliberately similar to the handling
84 of directories and zipfiles that are passed to the interpreter as the
89 This option cannot be used with built-in modules and extension modules
90 written in C, since they do not have Python module files. However, it
91 can still be used for precompiled modules, even if the original source
92 file is not available.
94 If this option is given, the first element of :data:`sys.argv` will be the
95 full path to the module file. As with the :option:`-c` option, the current
96 directory will be added to the start of :data:`sys.path`.
98 Many standard library modules contain code that is invoked on their execution
99 as a script. An example is the :mod:`timeit` module::
101 python -mtimeit -s 'setup here' 'benchmarked code here'
102 python -mtimeit -h # for details
105 :func:`runpy.run_module`
106 Equivalent functionality directly available to Python code
108 :pep:`338` -- Executing modules as scripts
110 .. versionadded:: 2.4
112 .. versionchanged:: 2.5
113 The named module can now be located inside a package.
115 .. versionchanged:: 2.7
116 Supply the package name to run a ``__main__`` submodule.
121 Read commands from standard input (:data:`sys.stdin`). If standard input is
122 a terminal, :option:`-i` is implied.
124 If this option is given, the first element of :data:`sys.argv` will be
125 ``"-"`` and the current directory will be added to the start of
129 .. describe:: <script>
131 Execute the Python code contained in *script*, which must be a filesystem
132 path (absolute or relative) referring to either a Python file, a directory
133 containing a ``__main__.py`` file, or a zipfile containing a
134 ``__main__.py`` file.
136 If this option is given, the first element of :data:`sys.argv` will be the
137 script name as given on the command line.
139 If the script name refers directly to a Python file, the directory
140 containing that file is added to the start of :data:`sys.path`, and the
141 file is executed as the :mod:`__main__` module.
143 If the script name refers to a directory or zipfile, the script name is
144 added to the start of :data:`sys.path` and the ``__main__.py`` file in
145 that location is executed as the :mod:`__main__` module.
147 .. versionchanged:: 2.5
148 Directories and zipfiles containing a ``__main__.py`` file at the top
149 level are now considered valid Python scripts.
151 If no interface option is given, :option:`-i` is implied, ``sys.argv[0]`` is
152 an empty string (``""``) and the current directory will be added to the
153 start of :data:`sys.path`.
155 .. seealso:: :ref:`tut-invoking`
165 Print a short description of all command line options.
167 .. versionchanged:: 2.5
168 The ``--help`` variant.
174 Print the Python version number and exit. Example output could be::
178 .. versionchanged:: 2.5
179 The ``--version`` variant.
182 Miscellaneous options
183 ~~~~~~~~~~~~~~~~~~~~~
187 If given, Python won't try to write ``.pyc`` or ``.pyo`` files on the
188 import of source modules. See also :envvar:`PYTHONDONTWRITEBYTECODE`.
190 .. versionadded:: 2.6
195 Turn on parser debugging output (for wizards only, depending on compilation
196 options). See also :envvar:`PYTHONDEBUG`.
201 Ignore all :envvar:`PYTHON*` environment variables, e.g.
202 :envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
204 .. versionadded:: 2.2
209 When a script is passed as first argument or the :option:`-c` option is used,
210 enter interactive mode after executing the script or the command, even when
211 :data:`sys.stdin` does not appear to be a terminal. The
212 :envvar:`PYTHONSTARTUP` file is not read.
214 This can be useful to inspect global variables or a stack trace when a script
215 raises an exception. See also :envvar:`PYTHONINSPECT`.
220 Turn on basic optimizations. This changes the filename extension for
221 compiled (:term:`bytecode`) files from ``.pyc`` to ``.pyo``. See also
222 :envvar:`PYTHONOPTIMIZE`.
227 Discard docstrings in addition to the :option:`-O` optimizations.
230 .. cmdoption:: -Q <arg>
232 Division control. The argument must be one of the following:
235 division of int/int and long/long return an int or long (*default*)
237 new division semantics, i.e. division of int/int and long/long returns a
240 old division semantics with a warning for int/int and long/long
242 old division semantics with a warning for all uses of the division operator
245 :file:`Tools/scripts/fixdiv.py`
246 for a use of ``warnall``
248 :pep:`238` -- Changing the division operator
253 Don't add user site directory to sys.path
255 .. versionadded:: 2.6
259 :pep:`370` -- Per user site-packages directory
264 Disable the import of the module :mod:`site` and the site-dependent
265 manipulations of :data:`sys.path` that it entails.
270 Issue a warning when a source file mixes tabs and spaces for indentation in a
271 way that makes it depend on the worth of a tab expressed in spaces. Issue an
272 error when the option is given twice (:option:`-tt`).
277 Force stdin, stdout and stderr to be totally unbuffered. On systems where it
278 matters, also put stdin, stdout and stderr in binary mode.
280 Note that there is internal buffering in :meth:`file.readlines` and
281 :ref:`bltin-file-objects` (``for line in sys.stdin``) which is not influenced
282 by this option. To work around this, you will want to use
283 :meth:`file.readline` inside a ``while 1:`` loop.
285 See also :envvar:`PYTHONUNBUFFERED`.
288 .. XXX should the -U option be documented?
292 Print a message each time a module is initialized, showing the place
293 (filename or built-in module) from which it is loaded. When given twice
294 (:option:`-vv`), print a message for each file that is checked for when
295 searching for a module. Also provides information on module cleanup at exit.
296 See also :envvar:`PYTHONVERBOSE`.
299 .. cmdoption:: -W arg
301 Warning control. Python's warning machinery by default prints warning
302 messages to :data:`sys.stderr`. A typical warning message has the following
305 file:line: category: message
307 By default, each warning is printed once for each source line where it
308 occurs. This option controls how often warnings are printed.
310 Multiple :option:`-W` options may be given; when a warning matches more than
311 one option, the action for the last matching option is performed. Invalid
312 :option:`-W` options are ignored (though, a warning message is printed about
313 invalid options when the first warning is issued).
315 Warnings can also be controlled from within a Python program using the
316 :mod:`warnings` module.
318 The simplest form of argument is one of the following action strings (or a
319 unique abbreviation):
324 Explicitly request the default behavior (printing each warning once per
327 Print a warning each time it occurs (this may generate many messages if a
328 warning is triggered repeatedly for the same source line, such as inside a
331 Print each warning only the first time it occurs in each module.
333 Print each warning only the first time it occurs in the program.
335 Raise an exception instead of printing a warning message.
337 The full form of argument is::
339 action:message:category:module:line
341 Here, *action* is as explained above but only applies to messages that match
342 the remaining fields. Empty fields match all values; trailing empty fields
343 may be omitted. The *message* field matches the start of the warning message
344 printed; this match is case-insensitive. The *category* field matches the
345 warning category. This must be a class name; the match test whether the
346 actual warning category of the message is a subclass of the specified warning
347 category. The full class name must be given. The *module* field matches the
348 (fully-qualified) module name; this match is case-sensitive. The *line*
349 field matches the line number, where zero matches all line numbers and is
350 thus equivalent to an omitted line number.
353 :mod:`warnings` -- the warnings module
355 :pep:`230` -- Warning framework
360 Skip the first line of the source, allowing use of non-Unix forms of
361 ``#!cmd``. This is intended for a DOS specific hack only.
363 .. note:: The line numbers in error messages will be off by one.
368 Warn about Python 3.x incompatibilities which cannot be fixed trivially by
369 :ref:`2to3 <2to3-reference>`. Among these are:
371 * :meth:`dict.has_key`
379 Using these will emit a :exc:`DeprecationWarning`.
381 .. versionadded:: 2.6
385 .. _using-on-envvars:
387 Environment variables
388 ---------------------
390 These environment variables influence Python's behavior.
392 .. envvar:: PYTHONHOME
394 Change the location of the standard Python libraries. By default, the
395 libraries are searched in :file:`{prefix}/lib/python{version}` and
396 :file:`{exec_prefix}/lib/python{version}`, where :file:`{prefix}` and
397 :file:`{exec_prefix}` are installation-dependent directories, both defaulting
398 to :file:`/usr/local`.
400 When :envvar:`PYTHONHOME` is set to a single directory, its value replaces
401 both :file:`{prefix}` and :file:`{exec_prefix}`. To specify different values
402 for these, set :envvar:`PYTHONHOME` to :file:`{prefix}:{exec_prefix}`.
405 .. envvar:: PYTHONPATH
407 Augment the default search path for module files. The format is the same as
408 the shell's :envvar:`PATH`: one or more directory pathnames separated by
409 :data:`os.pathsep` (e.g. colons on Unix or semicolons on Windows).
410 Non-existent directories are silently ignored.
412 In addition to normal directories, individual :envvar:`PYTHONPATH` entries
413 may refer to zipfiles containing pure Python modules (in either source or
414 compiled form). Extension modules cannot be imported from zipfiles.
416 The default search path is installation dependent, but generally begins with
417 :file:`{prefix}/lib/python{version}` (see :envvar:`PYTHONHOME` above). It
418 is *always* appended to :envvar:`PYTHONPATH`.
420 An additional directory will be inserted in the search path in front of
421 :envvar:`PYTHONPATH` as described above under
422 :ref:`using-on-interface-options`. The search path can be manipulated from
423 within a Python program as the variable :data:`sys.path`.
426 .. envvar:: PYTHONSTARTUP
428 If this is the name of a readable file, the Python commands in that file are
429 executed before the first prompt is displayed in interactive mode. The file
430 is executed in the same namespace where interactive commands are executed so
431 that objects defined or imported in it can be used without qualification in
432 the interactive session. You can also change the prompts :data:`sys.ps1` and
433 :data:`sys.ps2` in this file.
436 .. envvar:: PYTHONY2K
438 Set this to a non-empty string to cause the :mod:`time` module to require
439 dates specified as strings to include 4-digit years, otherwise 2-digit years
440 are converted based on rules described in the :mod:`time` module
444 .. envvar:: PYTHONOPTIMIZE
446 If this is set to a non-empty string it is equivalent to specifying the
447 :option:`-O` option. If set to an integer, it is equivalent to specifying
448 :option:`-O` multiple times.
451 .. envvar:: PYTHONDEBUG
453 If this is set to a non-empty string it is equivalent to specifying the
454 :option:`-d` option. If set to an integer, it is equivalent to specifying
455 :option:`-d` multiple times.
458 .. envvar:: PYTHONINSPECT
460 If this is set to a non-empty string it is equivalent to specifying the
463 This variable can also be modified by Python code using :data:`os.environ`
464 to force inspect mode on program termination.
467 .. envvar:: PYTHONUNBUFFERED
469 If this is set to a non-empty string it is equivalent to specifying the
473 .. envvar:: PYTHONVERBOSE
475 If this is set to a non-empty string it is equivalent to specifying the
476 :option:`-v` option. If set to an integer, it is equivalent to specifying
477 :option:`-v` multiple times.
480 .. envvar:: PYTHONCASEOK
482 If this is set, Python ignores case in :keyword:`import` statements. This
483 only works on Windows.
486 .. envvar:: PYTHONDONTWRITEBYTECODE
488 If this is set, Python won't try to write ``.pyc`` or ``.pyo`` files on the
489 import of source modules.
491 .. versionadded:: 2.6
493 .. envvar:: PYTHONIOENCODING
495 Overrides the encoding used for stdin/stdout/stderr, in the syntax
496 ``encodingname:errorhandler``. The ``:errorhandler`` part is optional and
497 has the same meaning as in :func:`str.encode`.
499 .. versionadded:: 2.6
502 .. envvar:: PYTHONNOUSERSITE
504 If this is set, Python won't add the user site directory to sys.path
506 .. versionadded:: 2.6
510 :pep:`370` -- Per user site-packages directory
513 .. envvar:: PYTHONUSERBASE
515 Sets the base directory for the user site directory
517 .. versionadded:: 2.6
521 :pep:`370` -- Per user site-packages directory
524 .. envvar:: PYTHONEXECUTABLE
526 If this environment variable is set, ``sys.argv[0]`` will be set to its
527 value instead of the value got through the C runtime. Only works on
534 Setting these variables only has an effect in a debug build of Python, that is,
535 if Python was configured with the :option:`--with-pydebug` build option.
537 .. envvar:: PYTHONTHREADDEBUG
539 If set, Python will print threading debug info.
541 .. versionchanged:: 2.6
542 Previously, this variable was called ``THREADDEBUG``.
544 .. envvar:: PYTHONDUMPREFS
546 If set, Python will dump objects and reference counts still alive after
547 shutting down the interpreter.
550 .. envvar:: PYTHONMALLOCSTATS
552 If set, Python will print memory allocation statistics every time a new
553 object arena is created, and on shutdown.