1 .. highlightlang:: none

     2 

     3 .. _using-on-general:

     4 

     5 Command line and environment

     6 ============================

     7 

     8 The CPython interpreter scans the command line and the environment for various

     9 settings.

    10 

    11 .. note:: 

    12    

    13    Other implementations' command line schemes may differ.  See

    14    :ref:`implementations` for further resources.

    15 

    16 

    17 .. _using-on-cmdline:

    18 

    19 Command line

    20 ------------

    21 

    22 When invoking Python, you may specify any of these options::

    23 

    24     python [-dEiOQsStuUvxX3?] [-c command | -m module-name | script | - ] [args]

    25 

    26 The most common use case is, of course, a simple invocation of a script::

    27 

    28     python myscript.py

    29 

    30 

    31 .. _using-on-interface-options:

    32 

    33 Interface options

    34 ~~~~~~~~~~~~~~~~~

    35 

    36 The interpreter interface resembles that of the UNIX shell, but provides some

    37 additional methods of invocation:

    38 

    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.

    51 

    52 In non-interactive mode, the entire input is parsed before it is executed.

    53 

    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

    57 source.

    58 

    59 .. cmdoption:: -c <command>

    60 

    61    Execute the Python code in *command*.  *command* can be one ore more

    62    statements separated by newlines, with significant leading whitespace as in

    63    normal module code.

    64    

    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

    68    level modules).

    69 

    70 

    71 .. cmdoption:: -m <module-name>

    72 

    73    Search :data:`sys.path` for the named module and execute its contents as

    74    the :mod:`__main__` module.

    75    

    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).

    80 

    81    .. note::

    82 

    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.

    87    

    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`.

    91    

    92    Many standard library modules contain code that is invoked on their execution

    93    as a script.  An example is the :mod:`timeit` module::

    94 

    95        python -mtimeit -s 'setup here' 'benchmarked code here'

    96        python -mtimeit -h # for details

    97 

    98    .. seealso:: 

    99       :func:`runpy.run_module`

   100          The actual implementation of this feature.

   101 

   102       :pep:`338` -- Executing modules as scripts

   103 

   104    .. versionadded:: 2.4

   105 

   106    .. versionchanged:: 2.5

   107       The named module can now be located inside a package.

   108 

   109 

   110 .. describe:: -

   111 

   112    Read commands from standard input (:data:`sys.stdin`).  If standard input is

   113    a terminal, :option:`-i` is implied.

   114 

   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

   117    :data:`sys.path`.

   118 

   119 

   120 .. describe:: <script>

   121 

   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.

   126 

   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.

   129 

   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.

   133 

   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.

   137 

   138    .. versionchanged:: 2.5

   139       Directories and zipfiles containing a ``__main__.py`` file at the top

   140       level are now considered valid Python scripts.

   141 

   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`.

   145 

   146 .. seealso::  :ref:`tut-invoking`

   147 

   148 

   149 Generic options

   150 ~~~~~~~~~~~~~~~

   151 

   152 .. cmdoption:: -?

   153                -h

   154                --help

   155 

   156    Print a short description of all command line options.

   157 

   158    .. versionchanged:: 2.5

   159       The ``--help`` variant.

   160 

   161 

   162 .. cmdoption:: -V

   163                --version

   164 

   165    Print the Python version number and exit.  Example output could be::

   166     

   167        Python 2.5.1

   168 

   169    .. versionchanged:: 2.5

   170       The ``--version`` variant.

   171 

   172 

   173 Miscellaneous options

   174 ~~~~~~~~~~~~~~~~~~~~~

   175 

   176 .. cmdoption:: -B

   177 

   178    If given, Python won't try to write ``.pyc`` or ``.pyo`` files on the

   179    import of source modules.  See also :envvar:`PYTHONDONTWRITEBYTECODE`.

   180 

   181    .. versionadded:: 2.6

   182 

   183 

   184 .. cmdoption:: -d

   185 

   186    Turn on parser debugging output (for wizards only, depending on compilation

   187    options).  See also :envvar:`PYTHONDEBUG`.

   188 

   189 

   190 .. cmdoption:: -E

   191 

   192    Ignore all :envvar:`PYTHON*` environment variables, e.g.

   193    :envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.

   194 

   195    .. versionadded:: 2.2

   196 

   197 

   198 .. cmdoption:: -i

   199 

   200    When a script is passed as first argument or the :option:`-c` option is used,

   201    enter interactive mode after executing the script or the command, even when

   202    :data:`sys.stdin` does not appear to be a terminal.  The

   203    :envvar:`PYTHONSTARTUP` file is not read.

   204    

   205    This can be useful to inspect global variables or a stack trace when a script

   206    raises an exception.  See also :envvar:`PYTHONINSPECT`.

   207 

   208 

   209 .. cmdoption:: -O

   210 

   211    Turn on basic optimizations.  This changes the filename extension for

   212    compiled (:term:`bytecode`) files from ``.pyc`` to ``.pyo``.  See also

   213    :envvar:`PYTHONOPTIMIZE`.

   214 

   215 

   216 .. cmdoption:: -OO

   217 

   218    Discard docstrings in addition to the :option:`-O` optimizations.

   219 

   220 

   221 .. cmdoption:: -Q <arg>

   222 

   223    Division control. The argument must be one of the following:

   224    

   225    ``old``

   226      division of int/int and long/long return an int or long (*default*)

   227    ``new``

   228      new division semantics, i.e. division of int/int and long/long returns a

   229      float

   230    ``warn``

   231      old division semantics with a warning for int/int and long/long

   232    ``warnall``

   233      old division semantics with a warning for all uses of the division operator

   234 

   235    .. seealso::

   236       :file:`Tools/scripts/fixdiv.py`

   237          for a use of ``warnall``

   238 

   239       :pep:`238` -- Changing the division operator

   240 

   241 

   242 .. cmdoption:: -s

   243 

   244    Don't add user site directory to sys.path

   245 

   246    .. versionadded:: 2.6

   247 

   248    .. seealso::

   249 

   250       :pep:`370` -- Per user site-packages directory

   251 

   252 

   253 .. cmdoption:: -S

   254 

   255    Disable the import of the module :mod:`site` and the site-dependent

   256    manipulations of :data:`sys.path` that it entails.

   257 

   258 

   259 .. cmdoption:: -t

   260 

   261    Issue a warning when a source file mixes tabs and spaces for indentation in a

   262    way that makes it depend on the worth of a tab expressed in spaces.  Issue an

   263    error when the option is given twice (:option:`-tt`).

   264 

   265 

   266 .. cmdoption:: -u

   267    

   268    Force stdin, stdout and stderr to be totally unbuffered.  On systems where it

   269    matters, also put stdin, stdout and stderr in binary mode.

   270    

   271    Note that there is internal buffering in :meth:`file.readlines` and

   272    :ref:`bltin-file-objects` (``for line in sys.stdin``) which is not influenced

   273    by this option.  To work around this, you will want to use

   274    :meth:`file.readline` inside a ``while 1:`` loop.

   275 

   276    See also :envvar:`PYTHONUNBUFFERED`.

   277 

   278 

   279 .. XXX should the -U option be documented?

   280 

   281 .. cmdoption:: -v

   282    

   283    Print a message each time a module is initialized, showing the place

   284    (filename or built-in module) from which it is loaded.  When given twice

   285    (:option:`-vv`), print a message for each file that is checked for when

   286    searching for a module.  Also provides information on module cleanup at exit.

   287    See also :envvar:`PYTHONVERBOSE`.

   288 

   289 

   290 .. cmdoption:: -W arg

   291    

   292    Warning control.  Python's warning machinery by default prints warning

   293    messages to :data:`sys.stderr`.  A typical warning message has the following

   294    form::

   295 

   296        file:line: category: message

   297        

   298    By default, each warning is printed once for each source line where it

   299    occurs.  This option controls how often warnings are printed.

   300 

   301    Multiple :option:`-W` options may be given; when a warning matches more than

   302    one option, the action for the last matching option is performed.  Invalid

   303    :option:`-W` options are ignored (though, a warning message is printed about

   304    invalid options when the first warning is issued).

   305    

   306    Warnings can also be controlled from within a Python program using the

   307    :mod:`warnings` module.

   308 

   309    The simplest form of argument is one of the following action strings (or a

   310    unique abbreviation):

   311     

   312    ``ignore``

   313       Ignore all warnings.

   314    ``default``

   315       Explicitly request the default behavior (printing each warning once per

   316       source line).

   317    ``all``

   318       Print a warning each time it occurs (this may generate many messages if a

   319       warning is triggered repeatedly for the same source line, such as inside a

   320       loop).

   321    ``module``

   322       Print each warning only only the first time it occurs in each module.

   323    ``once``

   324       Print each warning only the first time it occurs in the program.

   325    ``error``

   326       Raise an exception instead of printing a warning message.

   327       

   328    The full form of argument is:: 

   329    

   330        action:message:category:module:line

   331 

   332    Here, *action* is as explained above but only applies to messages that match

   333    the remaining fields.  Empty fields match all values; trailing empty fields

   334    may be omitted.  The *message* field matches the start of the warning message

   335    printed; this match is case-insensitive.  The *category* field matches the

   336    warning category.  This must be a class name; the match test whether the

   337    actual warning category of the message is a subclass of the specified warning

   338    category.  The full class name must be given.  The *module* field matches the

   339    (fully-qualified) module name; this match is case-sensitive.  The *line*

   340    field matches the line number, where zero matches all line numbers and is

   341    thus equivalent to an omitted line number.

   342 

   343    .. seealso::

   344       :mod:`warnings` -- the warnings module

   345 

   346       :pep:`230` -- Warning framework

   347 

   348 

   349 .. cmdoption:: -x

   350    

   351    Skip the first line of the source, allowing use of non-Unix forms of

   352    ``#!cmd``.  This is intended for a DOS specific hack only.

   353    

   354    .. warning:: The line numbers in error messages will be off by one!

   355 

   356 

   357 .. cmdoption:: -3

   358 

   359    Warn about Python 3.x incompatibilities. Among these are:

   360 

   361    * :meth:`dict.has_key`

   362    * :func:`apply`

   363    * :func:`callable`

   364    * :func:`coerce`

   365    * :func:`execfile`

   366    * :func:`reduce`

   367    * :func:`reload`

   368 

   369    Using these will emit a :exc:`DeprecationWarning`.

   370 

   371    .. versionadded:: 2.6

   372 

   373 

   374 

   375 .. _using-on-envvars:

   376 

   377 Environment variables

   378 ---------------------

   379 

   380 These environment variables influence Python's behavior.

   381 

   382 .. envvar:: PYTHONHOME

   383    

   384    Change the location of the standard Python libraries.  By default, the

   385    libraries are searched in :file:`{prefix}/lib/python{version}` and

   386    :file:`{exec_prefix}/lib/python{version}`, where :file:`{prefix}` and

   387    :file:`{exec_prefix}` are installation-dependent directories, both defaulting

   388    to :file:`/usr/local`.

   389    

   390    When :envvar:`PYTHONHOME` is set to a single directory, its value replaces

   391    both :file:`{prefix}` and :file:`{exec_prefix}`.  To specify different values

   392    for these, set :envvar:`PYTHONHOME` to :file:`{prefix}:{exec_prefix}`.

   393 

   394 

   395 .. envvar:: PYTHONPATH

   396 

   397    Augment the default search path for module files.  The format is the same as

   398    the shell's :envvar:`PATH`: one or more directory pathnames separated by

   399    :data:`os.pathsep` (e.g. colons on Unix or semicolons on Windows).

   400    Non-existent directories are silently ignored.

   401 

   402    In addition to normal directories, individual :envvar:`PYTHONPATH` entries

   403    may refer to zipfiles containing pure Python modules (in either source or

   404    compiled form). Extension modules cannot be imported from zipfiles.

   405    

   406    The default search path is installation dependent, but generally begins with

   407    :file:`{prefix}/lib/python{version}`` (see :envvar:`PYTHONHOME` above).  It

   408    is *always* appended to :envvar:`PYTHONPATH`.

   409    

   410    An additional directory will be inserted in the search path in front of

   411    :envvar:`PYTHONPATH` as described above under

   412    :ref:`using-on-interface-options`. The search path can be manipulated from

   413    within a Python program as the variable :data:`sys.path`.

   414 

   415 

   416 .. envvar:: PYTHONSTARTUP

   417    

   418    If this is the name of a readable file, the Python commands in that file are

   419    executed before the first prompt is displayed in interactive mode.  The file

   420    is executed in the same namespace where interactive commands are executed so

   421    that objects defined or imported in it can be used without qualification in

   422    the interactive session.  You can also change the prompts :data:`sys.ps1` and

   423    :data:`sys.ps2` in this file.

   424 

   425 

   426 .. envvar:: PYTHONY2K

   427    

   428    Set this to a non-empty string to cause the :mod:`time` module to require

   429    dates specified as strings to include 4-digit years, otherwise 2-digit years

   430    are converted based on rules described in the :mod:`time` module

   431    documentation.

   432 

   433 

   434 .. envvar:: PYTHONOPTIMIZE

   435    

   436    If this is set to a non-empty string it is equivalent to specifying the

   437    :option:`-O` option.  If set to an integer, it is equivalent to specifying

   438    :option:`-O` multiple times.

   439 

   440 

   441 .. envvar:: PYTHONDEBUG

   442    

   443    If this is set to a non-empty string it is equivalent to specifying the

   444    :option:`-d` option.  If set to an integer, it is equivalent to specifying

   445    :option:`-d` multiple times.

   446 

   447 

   448 .. envvar:: PYTHONINSPECT

   449    

   450    If this is set to a non-empty string it is equivalent to specifying the

   451    :option:`-i` option.

   452 

   453    This variable can also be modified by Python code using :data:`os.environ`

   454    to force inspect mode on program termination.

   455 

   456 

   457 .. envvar:: PYTHONUNBUFFERED

   458    

   459    If this is set to a non-empty string it is equivalent to specifying the

   460    :option:`-u` option.

   461 

   462 

   463 .. envvar:: PYTHONVERBOSE

   464    

   465    If this is set to a non-empty string it is equivalent to specifying the

   466    :option:`-v` option.  If set to an integer, it is equivalent to specifying

   467    :option:`-v` multiple times.

   468 

   469 

   470 .. envvar:: PYTHONCASEOK

   471    

   472    If this is set, Python ignores case in :keyword:`import` statements.  This

   473    only works on Windows.

   474 

   475 

   476 .. envvar:: PYTHONDONTWRITEBYTECODE

   477 

   478    If this is set, Python won't try to write ``.pyc`` or ``.pyo`` files on the

   479    import of source modules.

   480 

   481    .. versionadded:: 2.6

   482 

   483 .. envvar:: PYTHONIOENCODING

   484 

   485    Overrides the encoding used for stdin/stdout/stderr, in the syntax

   486    ``encodingname:errorhandler``.  The ``:errorhandler`` part is optional and

   487    has the same meaning as in :func:`str.encode`.

   488 

   489    .. versionadded:: 2.6

   490 

   491 

   492 .. envvar:: PYTHONNOUSERSITE

   493 

   494    If this is set, Python won't add the user site directory to sys.path

   495 

   496    .. versionadded:: 2.6

   497 

   498    .. seealso::

   499 

   500       :pep:`370` -- Per user site-packages directory

   501 

   502 

   503 .. envvar:: PYTHONUSERBASE

   504 

   505    Sets the base directory for the user site directory

   506 

   507    .. versionadded:: 2.6

   508 

   509    .. seealso::

   510 

   511       :pep:`370` -- Per user site-packages directory

   512 

   513 

   514 .. envvar:: PYTHONEXECUTABLE

   515 

   516    If this environment variable is set, ``sys.argv[0]`` will be set to its

   517    value instead of the value got through the C runtime.  Only works on

   518    Mac OS X.

   519 

   520 

   521 Debug-mode variables

   522 ~~~~~~~~~~~~~~~~~~~~

   523 

   524 Setting these variables only has an effect in a debug build of Python, that is,

   525 if Python was configured with the :option:`--with-pydebug` build option.

   526 

   527 .. envvar:: PYTHONTHREADDEBUG

   528 

   529    If set, Python will print threading debug info.

   530 

   531    .. versionchanged:: 2.6

   532       Previously, this variable was called ``THREADDEBUG``.

   533 

   534 .. envvar:: PYTHONDUMPREFS

   535 

   536    If set, Python will dump objects and reference counts still alive after

   537    shutting down the interpreter.

   538 

   539 

   540 .. envvar:: PYTHONMALLOCSTATS

   541 

   542    If set, Python will print memory allocation statistics every time a new

   543    object arena is created, and on shutdown.

   544