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                         * io.IOBase destructor logs close() exceptions
195
196                  -X utf8: enable UTF-8 mode for operating system  interfaces,
197              overriding the default
198                      locale-aware  mode.  -X utf8=0 explicitly disables UTF-8
199              mode (even when it would
200                      otherwise activate automatically).  See  PYTHONUTF8  for
201              more details
202
203                  -X  pycache_prefix=PATH: enable writing .pyc files to a par‐
204              allel tree rooted at the
205                       given directory instead of to the code tree.
206
207       -x     Skip the first line of the source.  This is intended for  a  DOS
208              specific hack only.  Warning: the line numbers in error messages
209              will be off by one!
210

INTERPRETER INTERFACE

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

FILES AND DIRECTORIES

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

ENVIRONMENT VARIABLES

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

AUTHOR

421       The Python Software Foundation: https://www.python.org/psf/
422

INTERNET RESOURCES

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

LICENSING

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