1PYTHON(1)                   General Commands Manual                  PYTHON(1)
2
3
4

NAME

6       python  - an interpreted, interactive, object-oriented programming lan‐
7       guage
8

SYNOPSIS

10       python [ -B ] [ -b ] [ -d ] [ -E ] [ -h ] [ -i ] [ -I ]
11              [ -m module-name ] [ -q ] [ -O ] [ -OO ] [ -s ] [ -S ] [ -u ]
12              [ -v ] [ -V ] [ -W argument ] [ -x ] [ [ -X option ] -?  ]
13              [ --check-hash-based-pycs default | always | never ]
14              [ -c command | script | - ] [ arguments ]
15

DESCRIPTION

17       Python is an interpreted, interactive, object-oriented programming lan‐
18       guage  that  combines  remarkable power with very clear syntax.  For an
19       introduction to programming in Python, see the  Python  Tutorial.   The
20       Python  Library  Reference  documents built-in and standard types, con‐
21       stants, functions and modules.  Finally, the  Python  Reference  Manual
22       describes  the  syntax  and  semantics of the core language in (perhaps
23       too) much detail.  (These documents may be  located  via  the  INTERNET
24       RESOURCES below; they may be installed on your system as well.)
25
26       Python's basic power can be extended with your own modules written in C
27       or C++.  On most  systems  such  modules  may  be  dynamically  loaded.
28       Python is also adaptable as an extension language for existing applica‐
29       tions.  See the internal documentation for hints.
30
31       Documentation for installed Python modules and packages can  be  viewed
32       by running the pydoc program.
33

COMMAND LINE OPTIONS

35       -B     Don't  write .pyc files on import. See also PYTHONDONTWRITEBYTE‐
36              CODE.
37
38       -b     Issue   warnings    about    str(bytes_instance),    str(bytear‐
39              ray_instance)  and  comparing  bytes/bytearray  with  str. (-bb:
40              issue errors)
41
42       -c command
43              Specify the command to execute (see next section).  This  termi‐
44              nates the option list (following options are passed as arguments
45              to the command).
46
47       --check-hash-based-pycs mode
48              Configure how Python evaluates the up-to-dateness of  hash-based
49              .pyc files.
50
51       -d     Turn  on  parser debugging output (for expert only, depending on
52              compilation options).
53
54       -E     Ignore environment variables like PYTHONPATH and PYTHONHOME that
55              modify the behavior of the interpreter.
56
57       -h ,  -? ,  --help
58              Prints the usage for the interpreter executable and exits.
59
60       -i     When  a  script  is passed as first argument or the -c option is
61              used, enter interactive mode after executing the script  or  the
62              command.  It does not read the $PYTHONSTARTUP file.  This can be
63              useful to inspect global variables  or  a  stack  trace  when  a
64              script raises an exception.
65
66       -I     Run  Python  in  isolated  mode. This also implies -E and -s. In
67              isolated mode sys.path contains neither the  script's  directory
68              nor  the user's site-packages directory. All PYTHON* environment
69              variables are ignored, too.  Further restrictions may be imposed
70              to prevent the user from injecting malicious code.
71
72       -m module-name
73              Searches  sys.path for the named module and runs the correspond‐
74              ing .py file as a script.
75
76       -O     Remove assert statements and any code conditional on  the  value
77              of __debug__; augment the filename for compiled (bytecode) files
78              by adding .opt-1 before the .pyc extension.
79
80       -OO    Do -O and also discard docstrings; change the filename for  com‐
81              piled  (bytecode)  files by adding .opt-2 before the .pyc exten‐
82              sion.
83
84       -q     Do not print the version and copyright messages. These  messages
85              are also suppressed in non-interactive mode.
86
87       -s     Don't add user site directory to sys.path.
88
89       -S     Disable  the  import  of  the module site and the site-dependent
90              manipulations of sys.path that it entails.  Also  disable  these
91              manipulations if site is explicitly imported later.
92
93       -u     Force  the  stdout  and  stderr  streams to be unbuffered.  This
94              option has no effect on the stdin stream.
95
96       -v     Print a message each time a module is initialized,  showing  the
97              place  (filename  or  built-in  module) from which it is loaded.
98              When given twice, print a message for each file that is  checked
99              for  when  searching for a module.  Also provides information on
100              module cleanup at exit.
101
102       -V ,  --version
103              Prints the Python version number of the  executable  and  exits.
104              When given twice, print more information about the build.
105
106       -W argument
107              Warning  control.   Python  sometimes  prints warning message to
108              sys.stderr.  A typical warning message has the  following  form:
109              file:line:  category:  message.   By  default,  each  warning is
110              printed once for each source line where it occurs.  This  option
111              controls  how  often  warnings are printed.  Multiple -W options
112              may be given; when a warning matches more than one  option,  the
113              action  for  the  last matching option is performed.  Invalid -W
114              options are ignored (a warning message is printed about  invalid
115              options when the first warning is issued).  Warnings can also be
116              controlled from within a Python program using the warnings  mod‐
117              ule.
118
119              The  simplest  form  of  argument is one of the following action
120              strings (or a unique abbreviation): ignore to ignore  all  warn‐
121              ings; default to explicitly request the default behavior (print‐
122              ing each warning once per source line); all to print  a  warning
123              each  time it occurs (this may generate many messages if a warn‐
124              ing is triggered repeatedly for the same source  line,  such  as
125              inside a loop); module to print each warning only the first time
126              it occurs in each module; once to print each  warning  only  the
127              first time it occurs in the program; or error to raise an excep‐
128              tion instead of printing a warning message.
129
130              The  full  form  of  argument  is   action:message:category:mod‐
131              ule:line.   Here,  action is as explained above but only applies
132              to messages that match the remaining fields.  Empty fields match
133              all  values;  trailing empty fields may be omitted.  The message
134              field matches the start of the  warning  message  printed;  this
135              match is case-insensitive.  The category field matches the warn‐
136              ing category.  This must be a class name; the match test whether
137              the  actual warning category of the message is a subclass of the
138              specified warning category.  The full class name must be  given.
139              The module field matches the (fully-qualified) module name; this
140              match is case-sensitive.  The line field matches the  line  num‐
141              ber,  where zero matches all line numbers and is thus equivalent
142              to an omitted line number.
143
144       -X option
145              Set implementation specific option. The  following  options  are
146              available:
147
148                  -X faulthandler: enable faulthandler
149
150                  -X showrefcount: output the total reference count and number
151              of used
152                      memory blocks when the program finishes  or  after  each
153              statement in the
154                      interactive interpreter. This only works on debug builds
155
156                  -X  tracemalloc:  start  tracing  Python  memory allocations
157              using the
158                      tracemalloc module. By default,  only  the  most  recent
159              frame is stored in a
160                      traceback of a trace. Use -X tracemalloc=NFRAME to start
161              tracing with a
162                      traceback limit of NFRAME frames
163
164                  -X showalloccount:  output  the  total  count  of  allocated
165              objects for each
166                      type  when  the  program  finishes. This only works when
167              Python was built with
168                      COUNT_ALLOCS defined
169
170                  -X importtime: show how long each  import  takes.  It  shows
171              module name,
172                      cumulative time (including nested imports) and self time
173              (excluding
174                      nested imports). Note that its output may be  broken  in
175              multi-threaded
176                      application.  Typical  usage is python3 -X importtime -c
177              'import asyncio'
178
179                  -X dev: enable  CPython’s  “development  mode”,  introducing
180              additional runtime
181                      checks which are too expensive to be enabled by default.
182              It will not be
183                      more verbose than the default if the  code  is  correct:
184              new warnings are
185                      only  emitted  when  an issue is detected. Effect of the
186              developer mode:
187                         * Add default warning filter, as -W default
188                         * Install debug hooks on memory allocators:  see  the
189              PyMem_SetupDebugHooks() C function
190                         *  Enable  the faulthandler module to dump the Python
191              traceback on a crash
192                         * Enable asyncio debug mode
193                         * Set the dev_mode attribute of sys.flags to True
194
195                  -X utf8: enable UTF-8 mode for operating system  interfaces,
196              overriding the default
197                      locale-aware  mode.  -X utf8=0 explicitly disables UTF-8
198              mode (even when it would
199                      otherwise activate automatically).  See  PYTHONUTF8  for
200              more details
201
202
203       -x     Skip  the  first line of the source.  This is intended for a DOS
204              specific hack only.  Warning: the line numbers in error messages
205              will be off by one!
206

INTERPRETER INTERFACE

208       The interpreter interface resembles that of the UNIX shell: when called
209       with standard input connected to a tty device, it prompts for  commands
210       and  executes  them  until an EOF is read; when called with a file name
211       argument or with a file as standard input,  it  reads  and  executes  a
212       script  from  that  file;  when called with -c command, it executes the
213       Python statement(s) given as command.  Here command may contain  multi‐
214       ple  statements  separated by newlines.  Leading whitespace is signifi‐
215       cant in Python statements!  In non-interactive mode, the  entire  input
216       is parsed before it is executed.
217
218       If  available,  the script name and additional arguments thereafter are
219       passed to the script in the Python variable sys.argv, which is  a  list
220       of  strings (you must first import sys to be able to access it).  If no
221       script name is given, sys.argv[0] is an empty string; if  -c  is  used,
222       sys.argv[0] contains the string '-c'.  Note that options interpreted by
223       the Python interpreter itself are not placed in sys.argv.
224
225       In interactive mode, the primary prompt is  `>>>';  the  second  prompt
226       (which  appears  when a command is not complete) is `...'.  The prompts
227       can be changed by assignment to sys.ps1 or  sys.ps2.   The  interpreter
228       quits  when  it  reads an EOF at a prompt.  When an unhandled exception
229       occurs, a stack trace is printed and control  returns  to  the  primary
230       prompt;  in  non-interactive mode, the interpreter exits after printing
231       the stack trace.  The interrupt  signal  raises  the  KeyboardInterrupt
232       exception;  other  UNIX  signals are not caught (except that SIGPIPE is
233       sometimes ignored, in favor of the IOError exception).  Error  messages
234       are written to stderr.
235

FILES AND DIRECTORIES

237       These are subject to difference depending on local installation conven‐
238       tions; ${prefix}  and  ${exec_prefix}  are  installation-dependent  and
239       should  be  interpreted as for GNU software; they may be the same.  The
240       default for both is /usr/local.
241
242       ${exec_prefix}/bin/python
243              Recommended location of the interpreter.
244
245       ${prefix}/lib/python<version>
246       ${exec_prefix}/lib/python<version>
247              Recommended locations of the directories containing the standard
248              modules.
249
250       ${prefix}/include/python<version>
251       ${exec_prefix}/include/python<version>
252              Recommended  locations of the directories containing the include
253              files needed for developing Python extensions and embedding  the
254              interpreter.
255

ENVIRONMENT VARIABLES

257       PYTHONHOME
258              Change  the  location  of  the  standard  Python  libraries.  By
259              default, the libraries are searched in ${prefix}/lib/python<ver‐
260              sion>  and  ${exec_prefix}/lib/python<version>,  where ${prefix}
261              and ${exec_prefix} are installation-dependent directories,  both
262              defaulting  to  /usr/local.  When $PYTHONHOME is set to a single
263              directory, its value replaces both ${prefix} and ${exec_prefix}.
264              To specify different values for these, set $PYTHONHOME to ${pre‐
265              fix}:${exec_prefix}.
266
267       PYTHONPATH
268              Augments the default search path for module files.   The  format
269              is  the  same  as the shell's $PATH: one or more directory path‐
270              names  separated  by  colons.   Non-existent   directories   are
271              silently  ignored.   The  default  search  path  is installation
272              dependent, but generally begins  with  ${prefix}/lib/python<ver‐
273              sion> (see PYTHONHOME above).  The default search path is always
274              appended to $PYTHONPATH.  If a script  argument  is  given,  the
275              directory containing the script is inserted in the path in front
276              of $PYTHONPATH.  The search path can be manipulated from  within
277              a Python program as the variable sys.path.
278
279       PYTHONSTARTUP
280              If  this  is the name of a readable file, the Python commands in
281              that file are executed before the first prompt is  displayed  in
282              interactive  mode.   The file is executed in the same name space
283              where interactive commands are executed so that objects  defined
284              or  imported  in  it  can  be  used without qualification in the
285              interactive session.  You can also change  the  prompts  sys.ps1
286              and sys.ps2 in this file.
287
288       PYTHONOPTIMIZE
289              If  this is set to a non-empty string it is equivalent to speci‐
290              fying the -O option. If set to an integer, it is  equivalent  to
291              specifying -O multiple times.
292
293       PYTHONDEBUG
294              If  this is set to a non-empty string it is equivalent to speci‐
295              fying the -d option. If set to an integer, it is  equivalent  to
296              specifying -d multiple times.
297
298       PYTHONDONTWRITEBYTECODE
299              If  this is set to a non-empty string it is equivalent to speci‐
300              fying the -B option (don't try to write .pyc files).
301
302       PYTHONINSPECT
303              If this is set to a non-empty string it is equivalent to  speci‐
304              fying the -i option.
305
306       PYTHONIOENCODING
307              If  this is set before running the interpreter, it overrides the
308              encoding used for stdin/stdout/stderr, in the  syntax  encoding‐
309              name:errorhandler  The errorhandler part is optional and has the
310              same meaning as in str.encode. For stderr, the errorhandler
311               part is ignored; the handler will always be ´backslashreplace´.
312
313       PYTHONNOUSERSITE
314              If this is set to a non-empty string it is equivalent to  speci‐
315              fying  the  -s  option  (Don't  add  the  user site directory to
316              sys.path).
317
318       PYTHONUNBUFFERED
319              If this is set to a non-empty string it is equivalent to  speci‐
320              fying the -u option.
321
322       PYTHONVERBOSE
323              If  this is set to a non-empty string it is equivalent to speci‐
324              fying the -v option. If set to an integer, it is  equivalent  to
325              specifying -v multiple times.
326
327       PYTHONWARNINGS
328              If  this  is set to a comma-separated string it is equivalent to
329              specifying the -W option for each separate value.
330
331       PYTHONHASHSEED
332              If this variable is set to "random", a random value is  used  to
333              seed the hashes of str, bytes and datetime objects.
334
335              If  PYTHONHASHSEED  is  set to an integer value, it is used as a
336              fixed seed for generating the hash() of the types covered by the
337              hash randomization.  Its purpose is to allow repeatable hashing,
338              such as for selftests for the interpreter itself, or to allow  a
339              cluster of python processes to share hash values.
340
341              The   integer   must   be   a   decimal   number  in  the  range
342              [0,4294967295].  Specifying the value 0 will disable  hash  ran‐
343              domization.
344
345       PYTHONMALLOC
346              Set the Python memory allocators and/or install debug hooks. The
347              available memory allocators are malloc and pymalloc.  The avail‐
348              able debug hooks are debug, malloc_debug, and pymalloc_debug.
349
350              When  Python  is  compiled  in debug mode, the default is pymal‐
351              loc_debug and the debug hooks are automatically used. Otherwise,
352              the default is pymalloc.
353
354       PYTHONMALLOCSTATS
355              If  set  to  a non-empty string, Python will print statistics of
356              the pymalloc memory allocator every time a new  pymalloc  object
357              arena is created, and on shutdown.
358
359              This  variable is ignored if the $PYTHONMALLOC environment vari‐
360              able is used to force the malloc(3) allocator of the C  library,
361              or if Python is configured without pymalloc support.
362
363       PYTHONASYNCIODEBUG
364              If  this  environment  variable  is  set  to a non-empty string,
365              enable the debug mode of the asyncio module.
366
367       PYTHONTRACEMALLOC
368              If this environment variable is set to a non-empty string, start
369              tracing Python memory allocations using the tracemalloc module.
370
371              The value of the variable is the maximum number of frames stored
372              in a traceback of  a  trace.  For  example,  PYTHONTRACEMALLOC=1
373              stores only the most recent frame.
374
375       PYTHONFAULTHANDLER
376              If  this  environment  variable  is  set  to a non-empty string,
377              faulthandler.enable() is called at startup:  install  a  handler
378              for  SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL signals to dump
379              the Python traceback.
380
381              This is equivalent to the -X faulthandler option.
382
383       PYTHONEXECUTABLE
384              If this environment variable is set, sys.argv[0] will be set  to
385              its  value  instead of the value got through the C runtime. Only
386              works on Mac OS X.
387
388       PYTHONUSERBASE
389              Defines the user base directory, which is used  to  compute  the
390              path of the user site-packages directory and Distutils installa‐
391              tion paths for python setup.py install --user.
392
393       PYTHONPROFILEIMPORTTIME
394              If this environment variable  is  set  to  a  non-empty  string,
395              Python  will  show  how  long each import takes. This is exactly
396              equivalent to setting -X importtime on the command line.
397
398       PYTHONBREAKPOINT
399              If this environment variable  is  set  to  0,  it  disables  the
400              default debugger. It can be set to the callable of your debugger
401              of choice.
402
403   Debug-mode variables
404       Setting these variables only has an effect in a debug build of  Python,
405       that is, if Python was configured with the --with-pydebug build option.
406
407       PYTHONTHREADDEBUG
408              If this environment variable is set, Python will print threading
409              debug info.
410
411       PYTHONDUMPREFS
412              If this environment variable is set, Python  will  dump  objects
413              and  reference counts still alive after shutting down the inter‐
414              preter.
415

AUTHOR

417       The Python Software Foundation: https://www.python.org/psf/
418

INTERNET RESOURCES

420       Main website:  https://www.python.org/
421       Documentation:  https://docs.python.org/
422       Developer resources:  https://devguide.python.org/
423       Downloads:  https://www.python.org/downloads/
424       Module repository:  https://pypi.org/
425       Newsgroups:  comp.lang.python, comp.lang.python.announce
426

LICENSING

428       Python is distributed under an  Open  Source  license.   See  the  file
429       "LICENSE"  in the Python source distribution for information on terms &
430       conditions for accessing and otherwise using  Python  and  for  a  DIS‐
431       CLAIMER OF ALL WARRANTIES.
432
433
434
435                                                                     PYTHON(1)
Impressum