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).
83 This option cannot be used with builtin modules and extension modules
84 written in C, since they do not have Python module files. However, it
85 can still be used for precompiled modules, even if the original source
86 file is not available.
88 If this option is given, the first element of :data:`sys.argv` will be the
89 full path to the module file. As with the :option:`-c` option, the current
90 directory will be added to the start of :data:`sys.path`.
92 Many standard library modules contain code that is invoked on their execution
93 as a script. An example is the :mod:`timeit` module::
95 python -mtimeit -s 'setup here' 'benchmarked code here'
96 python -mtimeit -h # for details
99 :func:`runpy.run_module`
100 The actual implementation of this feature.
102 :pep:`338` -- Executing modules as scripts
104 .. versionadded:: 2.4
106 .. versionchanged:: 2.5
107 The named module can now be located inside a package.
112 Read commands from standard input (:data:`sys.stdin`). If standard input is
113 a terminal, :option:`-i` is implied.
115 If this option is given, the first element of :data:`sys.argv` will be
116 ``"-"`` and the current directory will be added to the start of
120 .. describe:: <script>
122 Execute the Python code contained in *script*, which must be a filesystem
123 path (absolute or relative) referring to either a Python file, a directory
124 containing a ``__main__.py`` file, or a zipfile containing a
125 ``__main__.py`` file.
127 If this option is given, the first element of :data:`sys.argv` will be the
128 script name as given on the command line.
130 If the script name refers directly to a Python file, the directory
131 containing that file is added to the start of :data:`sys.path`, and the
132 file is executed as the :mod:`__main__` module.
134 If the script name refers to a directory or zipfile, the script name is
135 added to the start of :data:`sys.path` and the ``__main__.py`` file in
136 that location is executed as the :mod:`__main__` module.
138 .. versionchanged:: 2.5
139 Directories and zipfiles containing a ``__main__.py`` file at the top
140 level are now considered valid Python scripts.
142 If no interface option is given, :option:`-i` is implied, ``sys.argv[0]`` is
143 an empty string (``""``) and the current directory will be added to the
144 start of :data:`sys.path`.
157 Print a short description of all command line options.
159 .. versionchanged:: 2.5
160 The ``--help`` variant.
166 Print the Python version number and exit. Example output could be::
170 .. versionchanged:: 2.5
171 The ``--version`` variant.
174 Miscellaneous options
175 ~~~~~~~~~~~~~~~~~~~~~
179 If given, Python won't try to write ``.pyc`` or ``.pyo`` files on the
180 import of source modules. See also :envvar:`PYTHONDONTWRITEBYTECODE`.
182 .. versionadded:: 2.6
187 Turn on parser debugging output (for wizards only, depending on compilation
188 options). See also :envvar:`PYTHONDEBUG`.
193 Ignore all :envvar:`PYTHON*` environment variables, e.g.
194 :envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
196 .. versionadded:: 2.2
201 When a script is passed as first argument or the :option:`-c` option is used,
202 enter interactive mode after executing the script or the command, even when
203 :data:`sys.stdin` does not appear to be a terminal. The
204 :envvar:`PYTHONSTARTUP` file is not read.
206 This can be useful to inspect global variables or a stack trace when a script
207 raises an exception. See also :envvar:`PYTHONINSPECT`.
212 Turn on basic optimizations. This changes the filename extension for
213 compiled (:term:`bytecode`) files from ``.pyc`` to ``.pyo``. See also
214 :envvar:`PYTHONOPTIMIZE`.
219 Discard docstrings in addition to the :option:`-O` optimizations.
222 .. cmdoption:: -Q <arg>
224 Division control. The argument must be one of the following:
227 division of int/int and long/long return an int or long (*default*)
229 new division semantics, i.e. division of int/int and long/long returns a
232 old division semantics with a warning for int/int and long/long
234 old division semantics with a warning for all uses of the division operator
237 :file:`Tools/scripts/fixdiv.py`
238 for a use of ``warnall``
240 :pep:`238` -- Changing the division operator
245 Don't add user site directory to sys.path
247 .. versionadded:: 2.6
251 :pep:`370` -- Per user site-packages directory
256 Disable the import of the module :mod:`site` and the site-dependent
257 manipulations of :data:`sys.path` that it entails.
262 Issue a warning when a source file mixes tabs and spaces for indentation in a
263 way that makes it depend on the worth of a tab expressed in spaces. Issue an
264 error when the option is given twice (:option:`-tt`).
269 Force stdin, stdout and stderr to be totally unbuffered. On systems where it
270 matters, also put stdin, stdout and stderr in binary mode.
272 Note that there is internal buffering in :meth:`file.readlines` and
273 :ref:`bltin-file-objects` (``for line in sys.stdin``) which is not influenced
274 by this option. To work around this, you will want to use
275 :meth:`file.readline` inside a ``while 1:`` loop.
277 See also :envvar:`PYTHONUNBUFFERED`.
280 .. XXX should the -U option be documented?
284 Print a message each time a module is initialized, showing the place
285 (filename or built-in module) from which it is loaded. When given twice
286 (:option:`-vv`), print a message for each file that is checked for when
287 searching for a module. Also provides information on module cleanup at exit.
288 See also :envvar:`PYTHONVERBOSE`.
291 .. cmdoption:: -W arg
293 Warning control. Python's warning machinery by default prints warning
294 messages to :data:`sys.stderr`. A typical warning message has the following
297 file:line: category: message
299 By default, each warning is printed once for each source line where it
300 occurs. This option controls how often warnings are printed.
302 Multiple :option:`-W` options may be given; when a warning matches more than
303 one option, the action for the last matching option is performed. Invalid
304 :option:`-W` options are ignored (though, a warning message is printed about
305 invalid options when the first warning is issued).
307 Warnings can also be controlled from within a Python program using the
308 :mod:`warnings` module.
310 The simplest form of argument is one of the following action strings (or a
311 unique abbreviation):
316 Explicitly request the default behavior (printing each warning once per
319 Print a warning each time it occurs (this may generate many messages if a
320 warning is triggered repeatedly for the same source line, such as inside a
323 Print each warning only only the first time it occurs in each module.
325 Print each warning only the first time it occurs in the program.
327 Raise an exception instead of printing a warning message.
329 The full form of argument is::
331 action:message:category:module:line
333 Here, *action* is as explained above but only applies to messages that match
334 the remaining fields. Empty fields match all values; trailing empty fields
335 may be omitted. The *message* field matches the start of the warning message
336 printed; this match is case-insensitive. The *category* field matches the
337 warning category. This must be a class name; the match test whether the
338 actual warning category of the message is a subclass of the specified warning
339 category. The full class name must be given. The *module* field matches the
340 (fully-qualified) module name; this match is case-sensitive. The *line*
341 field matches the line number, where zero matches all line numbers and is
342 thus equivalent to an omitted line number.
345 :mod:`warnings` -- the warnings module
347 :pep:`230` -- Warning framework
352 Skip the first line of the source, allowing use of non-Unix forms of
353 ``#!cmd``. This is intended for a DOS specific hack only.
355 .. warning:: The line numbers in error messages will be off by one!
360 Warn about Python 3.x incompatibilities. Among these are:
362 * :meth:`dict.has_key`
370 Using these will emit a :exc:`DeprecationWarning`.
372 .. versionadded:: 2.6
376 .. _using-on-envvars:
378 Environment variables
379 ---------------------
381 These environment variables influence Python's behavior.
383 .. envvar:: PYTHONHOME
385 Change the location of the standard Python libraries. By default, the
386 libraries are searched in :file:`{prefix}/lib/python{version}` and
387 :file:`{exec_prefix}/lib/python{version}`, where :file:`{prefix}` and
388 :file:`{exec_prefix}` are installation-dependent directories, both defaulting
389 to :file:`/usr/local`.
391 When :envvar:`PYTHONHOME` is set to a single directory, its value replaces
392 both :file:`{prefix}` and :file:`{exec_prefix}`. To specify different values
393 for these, set :envvar:`PYTHONHOME` to :file:`{prefix}:{exec_prefix}`.
396 .. envvar:: PYTHONPATH
398 Augment the default search path for module files. The format is the same as
399 the shell's :envvar:`PATH`: one or more directory pathnames separated by
400 :data:`os.pathsep` (e.g. colons on Unix or semicolons on Windows).
401 Non-existent directories are silently ignored.
403 In addition to normal directories, individual :envvar:`PYTHONPATH` entries
404 may refer to zipfiles containing pure Python modules (in either source or
405 compiled form). Extension modules cannot be imported from zipfiles.
407 The default search path is installation dependent, but generally begins with
408 :file:`{prefix}/lib/python{version}`` (see :envvar:`PYTHONHOME` above). It
409 is *always* appended to :envvar:`PYTHONPATH`.
411 An additional directory will be inserted in the search path in front of
412 :envvar:`PYTHONPATH` as described above under
413 :ref:`using-on-interface-options`. The search path can be manipulated from
414 within a Python program as the variable :data:`sys.path`.
417 .. envvar:: PYTHONSTARTUP
419 If this is the name of a readable file, the Python commands in that file are
420 executed before the first prompt is displayed in interactive mode. The file
421 is executed in the same namespace where interactive commands are executed so
422 that objects defined or imported in it can be used without qualification in
423 the interactive session. You can also change the prompts :data:`sys.ps1` and
424 :data:`sys.ps2` in this file.
427 .. envvar:: PYTHONY2K
429 Set this to a non-empty string to cause the :mod:`time` module to require
430 dates specified as strings to include 4-digit years, otherwise 2-digit years
431 are converted based on rules described in the :mod:`time` module
435 .. envvar:: PYTHONOPTIMIZE
437 If this is set to a non-empty string it is equivalent to specifying the
438 :option:`-O` option. If set to an integer, it is equivalent to specifying
439 :option:`-O` multiple times.
442 .. envvar:: PYTHONDEBUG
444 If this is set to a non-empty string it is equivalent to specifying the
445 :option:`-d` option. If set to an integer, it is equivalent to specifying
446 :option:`-d` multiple times.
449 .. envvar:: PYTHONINSPECT
451 If this is set to a non-empty string it is equivalent to specifying the
454 This variable can also be modified by Python code using :data:`os.environ`
455 to force inspect mode on program termination.
458 .. envvar:: PYTHONUNBUFFERED
460 If this is set to a non-empty string it is equivalent to specifying the
464 .. envvar:: PYTHONVERBOSE
466 If this is set to a non-empty string it is equivalent to specifying the
467 :option:`-v` option. If set to an integer, it is equivalent to specifying
468 :option:`-v` multiple times.
471 .. envvar:: PYTHONCASEOK
473 If this is set, Python ignores case in :keyword:`import` statements. This
474 only works on Windows.
477 .. envvar:: PYTHONDONTWRITEBYTECODE
479 If this is set, Python won't try to write ``.pyc`` or ``.pyo`` files on the
480 import of source modules.
482 .. versionadded:: 2.6
484 .. envvar:: PYTHONIOENCODING
486 Overrides the encoding used for stdin/stdout/stderr, in the syntax
487 ``encodingname:errorhandler``. The ``:errorhandler`` part is optional and
488 has the same meaning as in :func:`str.encode`.
490 .. versionadded:: 2.6
493 .. envvar:: PYTHONNOUSERSITE
495 If this is set, Python won't add the user site directory to sys.path
497 .. versionadded:: 2.6
501 :pep:`370` -- Per user site-packages directory
504 .. envvar:: PYTHONUSERBASE
506 Sets the base directory for the user site directory
508 .. versionadded:: 2.6
512 :pep:`370` -- Per user site-packages directory
515 .. envvar:: PYTHONEXECUTABLE
517 If this environment variable is set, ``sys.argv[0]`` will be set to its
518 value instead of the value got through the C runtime. Only works on
525 Setting these variables only has an effect in a debug build of Python, that is,
526 if Python was configured with the :option:`--with-pydebug` build option.
528 .. envvar:: PYTHONTHREADDEBUG
530 If set, Python will print threading debug info.
532 .. versionchanged:: 2.6
533 Previously, this variable was called ``THREADDEBUG``.
535 .. envvar:: PYTHONDUMPREFS
537 If set, Python will dump objects and reference counts still alive after
538 shutting down the interpreter.
541 .. envvar:: PYTHONMALLOCSTATS
543 If set, Python will print memory allocation statistics every time a new
544 object arena is created, and on shutdown.