1PYTHON(1) General Commands Manual PYTHON(1)
2
6 python - an interpreted, interactive, object-oriented programming lan‐
7 guage
8
10 python [ -B ] [ -b ] [ -d ] [ -E ] [ -h ] [ -i ] [ -I ]
11 [ -m module-name ] [ -q ] [ -O ] [ -OO ] [ -P ] [ -s ] [ -S ] [
12 -u ]
13 [ -v ] [ -V ] [ -W argument ] [ -x ] [ -X option ] [ -? ]
14 [ --check-hash-based-pycs default | always | never ]
15 [ --help ] [ --help-env ] [ --help-xoptions ] [ --help-all ]
16 [ -c command | script | - ] [ arguments ]
17
19 Python is an interpreted, interactive, object-oriented programming lan‐
20 guage that combines remarkable power with very clear syntax. For an
21 introduction to programming in Python, see the Python Tutorial. The
22 Python Library Reference documents built-in and standard types, con‐
23 stants, functions and modules. Finally, the Python Reference Manual
24 describes the syntax and semantics of the core language in (perhaps
25 too) much detail. (These documents may be located via the INTERNET RE‐
26 SOURCES below; they may be installed on your system as well.)
27 Python's basic power can be extended with your own modules written in C
29 or C++. On most systems such modules may be dynamically loaded.
30 Python is also adaptable as an extension language for existing applica‐
31 tions. See the internal documentation for hints.
32 Documentation for installed Python modules and packages can be viewed
34 by running the pydoc program.
35
37 -B Don't write .pyc files on import. See also PYTHONDONTWRITEBYTE‐
38 CODE.
39 -b Issue warnings about str(bytes_instance), str(bytearray_in‐
41 stance) and comparing bytes/bytearray with str. (-bb: issue er‐
42 rors)
43 -c command
45 Specify the command to execute (see next section). This termi‐
46 nates the option list (following options are passed as arguments
47 to the command).
48 --check-hash-based-pycs mode
50 Configure how Python evaluates the up-to-dateness of hash-based
51 .pyc files.
52 -d Turn on parser debugging output (for expert only, depending on
54 compilation options).
55 -E Ignore environment variables like PYTHONPATH and PYTHONHOME that
57 modify the behavior of the interpreter.
58 -h , -? , --help
60 Prints the usage for the interpreter executable and exits.
61 --help-env
63 Prints help about Python-specific environment variables and ex‐
64 its.
65 --help-xoptions
67 Prints help about implementation-specific -X options and exits.
68 --help-all
71 Prints complete usage information and exits.
72 -i When a script is passed as first argument or the -c option is
74 used, enter interactive mode after executing the script or the
75 command. It does not read the $PYTHONSTARTUP file. This can be
76 useful to inspect global variables or a stack trace when a
77 script raises an exception.
78 -I Run Python in isolated mode. This also implies -E, -P and -s. In
80 isolated mode sys.path contains neither the script's directory
81 nor the user's site-packages directory. All PYTHON* environment
82 variables are ignored, too. Further restrictions may be imposed
83 to prevent the user from injecting malicious code.
84 -m module-name
86 Searches sys.path for the named module and runs the correspond‐
87 ing .py file as a script. This terminates the option list (fol‐
88 lowing options are passed as arguments to the module).
89 -O Remove assert statements and any code conditional on the value
91 of __debug__; augment the filename for compiled (bytecode) files
92 by adding .opt-1 before the .pyc extension.
93 -OO Do -O and also discard docstrings; change the filename for com‐
95 piled (bytecode) files by adding .opt-2 before the .pyc exten‐
96 sion.
97 -P Don't automatically prepend a potentially unsafe path to
99 sys.path such as the current directory, the script's directory
100 or an empty string. See also the PYTHONSAFEPATH environment
101 variable.
102 -q Do not print the version and copyright messages. These messages
104 are also suppressed in non-interactive mode.
105 -s Don't add user site directory to sys.path.
107 -S Disable the import of the module site and the site-dependent ma‐
109 nipulations of sys.path that it entails. Also disable these ma‐
110 nipulations if site is explicitly imported later.
111 -u Force the stdout and stderr streams to be unbuffered. This op‐
113 tion has no effect on the stdin stream.
114 -v Print a message each time a module is initialized, showing the
116 place (filename or built-in module) from which it is loaded.
117 When given twice, print a message for each file that is checked
118 for when searching for a module. Also provides information on
119 module cleanup at exit.
120 -V , --version
122 Prints the Python version number of the executable and exits.
123 When given twice, print more information about the build.
124 -W argument
127 Warning control. Python's warning machinery by default prints
128 warning messages to sys.stderr.
129 The simplest settings apply a particular action unconditionally
131 to all warnings emitted by a process (even those that are other‐
132 wise ignored by default):
133 -Wdefault # Warn once per call location
135 -Werror # Convert to exceptions
136 -Walways # Warn every time
137 -Wmodule # Warn once per calling module
138 -Wonce # Warn once per Python process
139 -Wignore # Never warn
140 The action names can be abbreviated as desired and the inter‐
142 preter will resolve them to the appropriate action name. For ex‐
143 ample, -Wi is the same as -Wignore .
144 The full form of argument is: action:message:category:mod‐
146 ule:lineno
147 Empty fields match all values; trailing empty fields may be
149 omitted. For example -W ignore::DeprecationWarning ignores all
150 DeprecationWarning warnings.
151 The action field is as explained above but only applies to warn‐
153 ings that match the remaining fields.
154 The message field must match the whole printed warning message;
156 this match is case-insensitive.
157 The category field matches the warning category (ex: "Depreca‐
159 tionWarning"). This must be a class name; the match test whether
160 the actual warning category of the message is a subclass of the
161 specified warning category.
162 The module field matches the (fully-qualified) module name; this
164 match is case-sensitive.
165 The lineno field matches the line number, where zero matches all
167 line numbers and is thus equivalent to an omitted line number.
168 Multiple -W options can be given; when a warning matches more
170 than one option, the action for the last matching option is per‐
171 formed. Invalid -W options are ignored (though, a warning mes‐
172 sage is printed about invalid options when the first warning is
173 issued).
174 Warnings can also be controlled using the PYTHONWARNINGS envi‐
176 ronment variable and from within a Python program using the
177 warnings module. For example, the warnings.filterwarnings()
178 function can be used to use a regular expression on the warning
179 message.
180 -X option
183 Set implementation-specific option. The following options are
184 available:
185 -X faulthandler: enable faulthandler
187 -X showrefcount: output the total reference count and number
189 of used
190 memory blocks when the program finishes or after each
191 statement in the
192 interactive interpreter. This only works on debug builds
193 -X tracemalloc: start tracing Python memory allocations us‐
195 ing the
196 tracemalloc module. By default, only the most recent
197 frame is stored in a
198 traceback of a trace. Use -X tracemalloc=NFRAME to start
199 tracing with a
200 traceback limit of NFRAME frames
201 -X importtime: show how long each import takes. It shows
203 module name,
204 cumulative time (including nested imports) and self time
205 (excluding
206 nested imports). Note that its output may be broken in
207 multi-threaded
208 application. Typical usage is python3 -X importtime -c
209 'import asyncio'
210 -X dev: enable CPython's "development mode", introducing ad‐
212 ditional runtime
213 checks which are too expensive to be enabled by default.
214 It will not be
215 more verbose than the default if the code is correct:
216 new warnings are
217 only emitted when an issue is detected. Effect of the
218 developer mode:
219 * Add default warning filter, as -W default
220 * Install debug hooks on memory allocators: see the
221 PyMem_SetupDebugHooks()
222 C function
223 * Enable the faulthandler module to dump the Python
224 traceback on a crash
225 * Enable asyncio debug mode
226 * Set the dev_mode attribute of sys.flags to True
227 * io.IOBase destructor logs close() exceptions
228 -X utf8: enable UTF-8 mode for operating system interfaces,
230 overriding the default
231 locale-aware mode. -X utf8=0 explicitly disables UTF-8
232 mode (even when it would
233 otherwise activate automatically). See PYTHONUTF8 for
234 more details
235 -X pycache_prefix=PATH: enable writing .pyc files to a par‐
237 allel tree rooted at the
238 given directory instead of to the code tree.
239 -X warn_default_encoding: enable opt-in EncodingWarning for
241 'encoding=None'
242 -X no_debug_ranges: disable the inclusion of the tables map‐
244 ping extra location
245 information (end line, start column offset and end column
246 offset) to every
247 instruction in code objects. This is useful when smaller
248 code objects and pyc
249 files are desired as well as suppressing the extra visual
250 location indicators
251 when the interpreter displays tracebacks.
252 -X frozen_modules=[on|off]: whether or not frozen modules
254 should be used.
255 The default is "on" (or "off" if you are running a local
256 build).
257 -X int_max_str_digits=number: limit the size of int<->str
259 conversions.
260 This helps avoid denial of service attacks when parsing
261 untrusted data.
262 The default is sys.int_info.default_max_str_digits. 0
263 disables.
264 -x Skip the first line of the source. This is intended for a DOS
267 specific hack only. Warning: the line numbers in error messages
268 will be off by one!
269
271 The interpreter interface resembles that of the UNIX shell: when called
272 with standard input connected to a tty device, it prompts for commands
273 and executes them until an EOF is read; when called with a file name
274 argument or with a file as standard input, it reads and executes a
275 script from that file; when called with -c command, it executes the
276 Python statement(s) given as command. Here command may contain multi‐
277 ple statements separated by newlines. Leading whitespace is signifi‐
278 cant in Python statements! In non-interactive mode, the entire input
279 is parsed before it is executed.
280 If available, the script name and additional arguments thereafter are
282 passed to the script in the Python variable sys.argv, which is a list
283 of strings (you must first import sys to be able to access it). If no
284 script name is given, sys.argv[0] is an empty string; if -c is used,
285 sys.argv[0] contains the string '-c'. Note that options interpreted by
286 the Python interpreter itself are not placed in sys.argv.
287 In interactive mode, the primary prompt is `>>>'; the second prompt
289 (which appears when a command is not complete) is `...'. The prompts
290 can be changed by assignment to sys.ps1 or sys.ps2. The interpreter
291 quits when it reads an EOF at a prompt. When an unhandled exception
292 occurs, a stack trace is printed and control returns to the primary
293 prompt; in non-interactive mode, the interpreter exits after printing
294 the stack trace. The interrupt signal raises the KeyboardInterrupt ex‐
295 ception; other UNIX signals are not caught (except that SIGPIPE is
296 sometimes ignored, in favor of the IOError exception). Error messages
297 are written to stderr.
298
300 These are subject to difference depending on local installation conven‐
301 tions; ${prefix} and ${exec_prefix} are installation-dependent and
302 should be interpreted as for GNU software; they may be the same. The
303 default for both is /usr/local.
304 ${exec_prefix}/bin/python
306 Recommended location of the interpreter.
307 ${prefix}/lib/python<version>
309 ${exec_prefix}/lib/python<version>
310 Recommended locations of the directories containing the standard
311 modules.
312 ${prefix}/include/python<version>
314 ${exec_prefix}/include/python<version>
315 Recommended locations of the directories containing the include
316 files needed for developing Python extensions and embedding the
317 interpreter.
318
320 PYTHONSAFEPATH
321 If this is set to a non-empty string, don't automatically
322 prepend a potentially unsafe path to sys.path such as the cur‐
323 rent directory, the script's directory or an empty string. See
324 also the -P option.
325 PYTHONHOME
327 Change the location of the standard Python libraries. By de‐
328 fault, the libraries are searched in ${prefix}/lib/python<ver‐
329 sion> and ${exec_prefix}/lib/python<version>, where ${prefix}
330 and ${exec_prefix} are installation-dependent directories, both
331 defaulting to /usr/local. When $PYTHONHOME is set to a single
332 directory, its value replaces both ${prefix} and ${exec_prefix}.
333 To specify different values for these, set $PYTHONHOME to ${pre‐
334 fix}:${exec_prefix}.
335 PYTHONPATH
337 Augments the default search path for module files. The format
338 is the same as the shell's $PATH: one or more directory path‐
339 names separated by colons. Non-existent directories are
340 silently ignored. The default search path is installation de‐
341 pendent, but generally begins with ${prefix}/lib/python<version>
342 (see PYTHONHOME above). The default search path is always ap‐
343 pended to $PYTHONPATH. If a script argument is given, the di‐
344 rectory containing the script is inserted in the path in front
345 of $PYTHONPATH. The search path can be manipulated from within
346 a Python program as the variable sys.path.
347 PYTHONPLATLIBDIR
349 Override sys.platlibdir.
350 PYTHONSTARTUP
352 If this is the name of a readable file, the Python commands in
353 that file are executed before the first prompt is displayed in
354 interactive mode. The file is executed in the same name space
355 where interactive commands are executed so that objects defined
356 or imported in it can be used without qualification in the in‐
357 teractive session. You can also change the prompts sys.ps1 and
358 sys.ps2 in this file.
359 PYTHONOPTIMIZE
361 If this is set to a non-empty string it is equivalent to speci‐
362 fying the -O option. If set to an integer, it is equivalent to
363 specifying -O multiple times.
364 PYTHONDEBUG
366 If this is set to a non-empty string it is equivalent to speci‐
367 fying the -d option. If set to an integer, it is equivalent to
368 specifying -d multiple times.
369 PYTHONDONTWRITEBYTECODE
371 If this is set to a non-empty string it is equivalent to speci‐
372 fying the -B option (don't try to write .pyc files).
373 PYTHONINSPECT
375 If this is set to a non-empty string it is equivalent to speci‐
376 fying the -i option.
377 PYTHONIOENCODING
379 If this is set before running the interpreter, it overrides the
380 encoding used for stdin/stdout/stderr, in the syntax encoding‐
381 name:errorhandler The errorhandler part is optional and has the
382 same meaning as in str.encode. For stderr, the errorhandler
383 part is ignored; the handler will always be ´backslashreplace´.
384 PYTHONNOUSERSITE
386 If this is set to a non-empty string it is equivalent to speci‐
387 fying the -s option (Don't add the user site directory to
388 sys.path).
389 PYTHONUNBUFFERED
391 If this is set to a non-empty string it is equivalent to speci‐
392 fying the -u option.
393 PYTHONVERBOSE
395 If this is set to a non-empty string it is equivalent to speci‐
396 fying the -v option. If set to an integer, it is equivalent to
397 specifying -v multiple times.
398 PYTHONWARNINGS
400 If this is set to a comma-separated string it is equivalent to
401 specifying the -W option for each separate value.
402 PYTHONHASHSEED
404 If this variable is set to "random", a random value is used to
405 seed the hashes of str and bytes objects.
406 If PYTHONHASHSEED is set to an integer value, it is used as a
408 fixed seed for generating the hash() of the types covered by the
409 hash randomization. Its purpose is to allow repeatable hashing,
410 such as for selftests for the interpreter itself, or to allow a
411 cluster of python processes to share hash values.
412 The integer must be a decimal number in the range
414 [0,4294967295]. Specifying the value 0 will disable hash ran‐
415 domization.
416 PYTHONINTMAXSTRDIGITS
418 Limit the maximum digit characters in an int value when convert‐
419 ing from a string and when converting an int back to a str. A
420 value of 0 disables the limit. Conversions to or from bases 2,
421 4, 8, 16, and 32 are never limited.
422 PYTHONMALLOC
424 Set the Python memory allocators and/or install debug hooks. The
425 available memory allocators are malloc and pymalloc. The avail‐
426 able debug hooks are debug, malloc_debug, and pymalloc_debug.
427 When Python is compiled in debug mode, the default is pymal‐
429 loc_debug and the debug hooks are automatically used. Otherwise,
430 the default is pymalloc.
431 PYTHONMALLOCSTATS
433 If set to a non-empty string, Python will print statistics of
434 the pymalloc memory allocator every time a new pymalloc object
435 arena is created, and on shutdown.
436 This variable is ignored if the $PYTHONMALLOC environment vari‐
438 able is used to force the malloc(3) allocator of the C library,
439 or if Python is configured without pymalloc support.
440 PYTHONASYNCIODEBUG
442 If this environment variable is set to a non-empty string, en‐
443 able the debug mode of the asyncio module.
444 PYTHONTRACEMALLOC
446 If this environment variable is set to a non-empty string, start
447 tracing Python memory allocations using the tracemalloc module.
448 The value of the variable is the maximum number of frames stored
450 in a traceback of a trace. For example, PYTHONTRACEMALLOC=1
451 stores only the most recent frame.
452 PYTHONFAULTHANDLER
454 If this environment variable is set to a non-empty string,
455 faulthandler.enable() is called at startup: install a handler
456 for SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL signals to dump
457 the Python traceback.
458 This is equivalent to the -X faulthandler option.
460 PYTHONEXECUTABLE
462 If this environment variable is set, sys.argv[0] will be set to
463 its value instead of the value got through the C runtime. Only
464 works on Mac OS X.
465 PYTHONUSERBASE
467 Defines the user base directory, which is used to compute the
468 path of the user site-packages directory and installation paths
469 for python -m pip install --user.
470 PYTHONPROFILEIMPORTTIME
472 If this environment variable is set to a non-empty string,
473 Python will show how long each import takes. This is exactly
474 equivalent to setting -X importtime on the command line.
475 PYTHONBREAKPOINT
477 If this environment variable is set to 0, it disables the de‐
478 fault debugger. It can be set to the callable of your debugger
479 of choice.
480 Debug-mode variables
482 Setting these variables only has an effect in a debug build of Python,
483 that is, if Python was configured with the --with-pydebug build option.
484 PYTHONDUMPREFS
486 If this environment variable is set, Python will dump objects
487 and reference counts still alive after shutting down the inter‐
488 preter.
489
491 The Python Software Foundation: https://www.python.org/psf/
492
494 Main website: https://www.python.org/
495 Documentation: https://docs.python.org/
496 Developer resources: https://devguide.python.org/
497 Downloads: https://www.python.org/downloads/
498 Module repository: https://pypi.org/
499 Newsgroups: comp.lang.python, comp.lang.python.announce
500
502 Python is distributed under an Open Source license. See the file "LI‐
503 CENSE" in the Python source distribution for information on terms &
504 conditions for accessing and otherwise using Python and for a DIS‐
505 CLAIMER OF ALL WARRANTIES.
506 PYTHON(1)