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 importtime: show how long each  import  takes.  It  shows
165              module name,
166                      cumulative time (including nested imports) and self time
167              (excluding
168                      nested imports). Note that its output may be  broken  in
169              multi-threaded
170                      application.  Typical  usage is python3 -X importtime -c
171              'import asyncio'
172
173                  -X dev: enable  CPython's  "development  mode",  introducing
174              additional runtime
175                      checks which are too expensive to be enabled by default.
176              It will not be
177                      more verbose than the default if the  code  is  correct:
178              new warnings are
179                      only  emitted  when  an issue is detected. Effect of the
180              developer mode:
181                         * Add default warning filter, as -W default
182                         * Install debug hooks on memory allocators:  see  the
183              PyMem_SetupDebugHooks() C function
184                         *  Enable  the faulthandler module to dump the Python
185              traceback on a crash
186                         * Enable asyncio debug mode
187                         * Set the dev_mode attribute of sys.flags to True
188                         * io.IOBase destructor logs close() exceptions
189
190                  -X utf8: enable UTF-8 mode for operating system  interfaces,
191              overriding the default
192                      locale-aware  mode.  -X utf8=0 explicitly disables UTF-8
193              mode (even when it would
194                      otherwise activate automatically).  See  PYTHONUTF8  for
195              more details
196
197                  -X  pycache_prefix=PATH: enable writing .pyc files to a par‐
198              allel tree rooted at the
199                       given directory instead of to the code tree.
200
201       -x     Skip the first line of the source.  This is intended for  a  DOS
202              specific hack only.  Warning: the line numbers in error messages
203              will be off by one!
204

INTERPRETER INTERFACE

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

FILES AND DIRECTORIES

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

ENVIRONMENT VARIABLES

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

AUTHOR

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

INTERNET RESOURCES

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

LICENSING

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