1.1.1. Interface options¶

The interpreter interface resembles that of the UNIX shell, but provides someadditional methods of invocation:

• When called with standard input connected to a tty device, it prompts forcommands and executes them until an EOF (an end-of-file character, you canproduce that withCtrl-D on UNIX orCtrl-Z, Enter on Windows) is read.
• When called with a file name argument or with a file as standard input, itreads and executes a script from that file.
• When called with a directory name argument, it reads and executes anappropriately named script from that directory.
• When called with-ccommand, it executes the Python statement(s) given ascommand. Herecommand may contain multiple statements separated bynewlines. Leading whitespace is significant in Python statements!
• When called with-mmodule-name, the given module is located on thePython module path and executed as a script.

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

An interface option terminates the list of options consumed by the interpreter,all consecutive arguments will end up insys.argv – note that the firstelement, subscript zero (sys.argv[0]), is a string reflecting the program’ssource.

-c <command>¶

Execute the Python code incommand.command can be one or morestatements separated by newlines, with significant leading whitespace as innormal module code.

If this option is given, the first element ofsys.argv will be"-c" and the current directory will be added to the start ofsys.path (allowing modules in that directory to be imported as toplevel modules).

-m <module-name>¶

Searchsys.path for the named module and execute its contents asthe__main__ module.

Since the argument is amodule name, you must not give a file extension(.py). The module name should be a valid absolute Python module name, butthe implementation may not always enforce this (e.g. it may allow you touse a name that includes a hyphen).

Package names (including namespace packages) are also permitted. When apackage name is supplied insteadof a normal module, the interpreter will execute<pkg>.__main__ asthe main module. This behaviour is deliberately similar to the handlingof directories and zipfiles that are passed to the interpreter as thescript argument.

Note

This option cannot be used with built-in modules and extension moduleswritten in C, since they do not have Python module files. However, itcan still be used for precompiled modules, even if the original sourcefile is not available.

If this option is given, the first element ofsys.argv will be thefull path to the module file (while the module file is being located, thefirst element will be set to"-m"). As with the-c option,the current directory will be added to the start ofsys.path.

Many standard library modules contain code that is invoked on their executionas a script. An example is thetimeit module:

python-mtimeit-s'setup here''benchmarked code here'python-mtimeit-h# for details

See also

runpy.run_module()

Equivalent functionality directly available to Python code

PEP 338 – Executing modules as scripts

Changed in version 3.1:Supply the package name to run a__main__ submodule.

Changed in version 3.4:namespace packages are also supported

-

Read commands from standard input (sys.stdin). If standard input isa terminal,-i is implied.

If this option is given, the first element ofsys.argv will be"-" and the current directory will be added to the start ofsys.path.

<script>

Execute the Python code contained inscript, which must be a filesystempath (absolute or relative) referring to either a Python file, a directorycontaining a__main__.py file, or a zipfile containing a__main__.py file.

If this option is given, the first element ofsys.argv will be thescript name as given on the command line.

If the script name refers directly to a Python file, the directorycontaining that file is added to the start ofsys.path, and thefile is executed as the__main__ module.

If the script name refers to a directory or zipfile, the script name isadded to the start ofsys.path and the__main__.py file inthat location is executed as the__main__ module.

See also

runpy.run_path()

Equivalent functionality directly available to Python code

If no interface option is given,-i is implied,sys.argv[0] isan empty string ("") and the current directory will be added to thestart ofsys.path. Also, tab-completion and history editing isautomatically enabled, if available on your platform (seeReadline configuration).

1.1.2. Generic options¶

-?¶

-h¶

--help¶

Print a short description of all command line options.

-V¶

--version¶

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

Python3.0

1.1.3. Miscellaneous options¶

-b¶

Issue a warning when comparingbytes orbytearray withstr orbytes withint. Issue an error when theoption is given twice (-bb).

Changed in version 3.5:Affects comparisons ofbytes withint.

-B¶

If given, Python won’t try to write.pyc files on theimport of source modules. See alsoPYTHONDONTWRITEBYTECODE.

-d¶

Turn on parser debugging output (for wizards only, depending on compilationoptions). See alsoPYTHONDEBUG.

-E¶

Ignore allPYTHON* environment variables, e.g.PYTHONPATH andPYTHONHOME, that might be set.

-i¶

When a script is passed as first argument or the-c option is used,enter interactive mode after executing the script or the command, even whensys.stdin does not appear to be a terminal. ThePYTHONSTARTUP file is not read.

This can be useful to inspect global variables or a stack trace when a scriptraises an exception. See alsoPYTHONINSPECT.

-I¶

Run Python in isolated mode. This also implies -E and -s.In isolated modesys.path contains neither the script’s directory northe user’s site-packages directory. AllPYTHON* environmentvariables are ignored, too. Further restrictions may be imposed to preventthe user from injecting malicious code.

New in version 3.4.

-O¶

Turn on basic optimizations. See alsoPYTHONOPTIMIZE.

-OO¶

Discard docstrings in addition to the-O optimizations.

-q¶

Don’t display the copyright and version messages even in interactive mode.

New in version 3.2.

-R¶

Kept for compatibility. On Python 3.3 and greater, hash randomization isturned on by default.

On previous versions of Python, this option turns on hash randomization,so that the__hash__() values of str, bytes and datetimeare “salted” with an unpredictable random value. Although they remainconstant within an individual Python process, they are not predictablebetween repeated invocations of Python.

Hash randomization is intended to provide protection against adenial-of-service caused by carefully-chosen inputs that exploit the worstcase performance of a dict construction, O(n^2) complexity. Seehttp://www.ocert.org/advisories/ocert-2011-003.html for details.

PYTHONHASHSEED allows you to set a fixed value for the hashseed secret.

New in version 3.2.3.

-s¶

Don’t add theusersite-packagesdirectory tosys.path.

See also

PEP 370 – Per user site-packages directory

-S¶

Disable the import of the modulesite and the site-dependentmanipulations ofsys.path that it entails. Also disable thesemanipulations ifsite is explicitly imported later (callsite.main() if you want them to be triggered).

-u¶

Force the binary layer of the stdout and stderr streams (which isavailable as theirbuffer attribute) to be unbuffered. The text I/Olayer will still be line-buffered if writing to the console, orblock-buffered if redirected to a non-interactive file.

See alsoPYTHONUNBUFFERED.

-v¶

Print a message each time a module is initialized, showing the place(filename or built-in module) from which it is loaded. When given twice(-vv), print a message for each file that is checked for whensearching for a module. Also provides information on module cleanup at exit.See alsoPYTHONVERBOSE.

-W arg¶

Warning control. Python’s warning machinery by default prints warningmessages tosys.stderr. A typical warning message has the followingform:

file:line:category:message

By default, each warning is printed once for each source line where itoccurs. This option controls how often warnings are printed.

Multiple-W options may be given; when a warning matches more thanone option, the action for the last matching option is performed. Invalid-W options are ignored (though, a warning message is printed aboutinvalid options when the first warning is issued).

Warnings can also be controlled from within a Python program using thewarnings module.

The simplest form of argument is one of the following action strings (or aunique abbreviation):

ignore

Ignore all warnings.

default

Explicitly request the default behavior (printing each warning once persource line).

all

Print a warning each time it occurs (this may generate many messages if awarning is triggered repeatedly for the same source line, such as inside aloop).

module

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

once

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

error

Raise an exception instead of printing a warning message.

The full form of argument is:

action:message:category:module:line

Here,action is as explained above but only applies to messages that matchthe remaining fields. Empty fields match all values; trailing empty fieldsmay be omitted. Themessage field matches the start of the warning messageprinted; this match is case-insensitive. Thecategory field matches thewarning category. This must be a class name; the match tests whether theactual warning category of the message is a subclass of the specified warningcategory. The full class name must be given. Themodule field matches the(fully-qualified) module name; this match is case-sensitive. Thelinefield matches the line number, where zero matches all line numbers and isthus equivalent to an omitted line number.

See also

warnings – the warnings module

PEP 230 – Warning framework

PYTHONWARNINGS

-x¶

Skip the first line of the source, allowing use of non-Unix forms of#!cmd. This is intended for a DOS specific hack only.

Note

The line numbers in error messages will be off by one.

-X¶

Reserved for various implementation-specific options. CPython currentlydefines the following possible values:

• -Xfaulthandler to enablefaulthandler;
• -Xshowrefcount to enable the output of the total reference countand memory blocks (only works on debug builds);
• -Xtracemalloc to start tracing Python memory allocations using thetracemalloc module. By default, only the most recent frame isstored in a traceback of a trace. Use-Xtracemalloc=NFRAME to starttracing with a traceback limit ofNFRAME frames. See thetracemalloc.start() for more information.

It also allows passing arbitrary values and retrieving them through thesys._xoptions dictionary.

Changed in version 3.2:It is now allowed to pass-X with CPython.

New in version 3.3:The-Xfaulthandler option.

New in version 3.4:The-Xshowrefcount and-Xtracemalloc options.

1.1.4. Options you shouldn’t use¶

-J¶

Reserved for use byJython.

1.2.1. Debug-mode variables¶

Setting these variables only has an effect in a debug build of Python, that is,if Python was configured with the--with-pydebug build option.

PYTHONTHREADDEBUG¶

If set, Python will print threading debug info.

PYTHONDUMPREFS¶

If set, Python will dump objects and reference counts still alive aftershutting down the interpreter.

PYTHONMALLOCSTATS¶

If set, Python will print memory allocation statistics every time a newobject arena is created, and on shutdown.