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 Skip the first line of the source. This is intended for a DOS
260 specific hack only. Warning: the line numbers in error messages
261 will be off by one!
262
264 The interpreter interface resembles that of the UNIX shell: when called
265 with standard input connected to a tty device, it prompts for commands
266 and executes them until an EOF is read; when called with a file name
267 argument or with a file as standard input, it reads and executes a
268 script from that file; when called with -c command, it executes the
269 Python statement(s) given as command. Here command may contain multi‐
270 ple statements separated by newlines. Leading whitespace is signifi‐
271 cant in Python statements! In non-interactive mode, the entire input
272 is parsed before it is executed.
273 If available, the script name and additional arguments thereafter are
275 passed to the script in the Python variable sys.argv, which is a list
276 of strings (you must first import sys to be able to access it). If no
277 script name is given, sys.argv[0] is an empty string; if -c is used,
278 sys.argv[0] contains the string '-c'. Note that options interpreted by
279 the Python interpreter itself are not placed in sys.argv.
280 In interactive mode, the primary prompt is `>>>'; the second prompt
282 (which appears when a command is not complete) is `...'. The prompts
283 can be changed by assignment to sys.ps1 or sys.ps2. The interpreter
284 quits when it reads an EOF at a prompt. When an unhandled exception
285 occurs, a stack trace is printed and control returns to the primary
286 prompt; in non-interactive mode, the interpreter exits after printing
287 the stack trace. The interrupt signal raises the KeyboardInterrupt ex‐
288 ception; other UNIX signals are not caught (except that SIGPIPE is
289 sometimes ignored, in favor of the IOError exception). Error messages
290 are written to stderr.
291
293 These are subject to difference depending on local installation conven‐
294 tions; ${prefix} and ${exec_prefix} are installation-dependent and
295 should be interpreted as for GNU software; they may be the same. The
296 default for both is /usr/local.
297 ${exec_prefix}/bin/python
299 Recommended location of the interpreter.
300 ${prefix}/lib/python<version>
302 ${exec_prefix}/lib/python<version>
303 Recommended locations of the directories containing the standard
304 modules.
305 ${prefix}/include/python<version>
307 ${exec_prefix}/include/python<version>
308 Recommended locations of the directories containing the include
309 files needed for developing Python extensions and embedding the
310 interpreter.
311
313 PYTHONSAFEPATH
314 If this is set to a non-empty string, don't automatically
315 prepend a potentially unsafe path to sys.path such as the cur‐
316 rent directory, the script's directory or an empty string. See
317 also the -P option.
318 PYTHONHOME
320 Change the location of the standard Python libraries. By de‐
321 fault, the libraries are searched in ${prefix}/lib/python<ver‐
322 sion> and ${exec_prefix}/lib/python<version>, where ${prefix}
323 and ${exec_prefix} are installation-dependent directories, both
324 defaulting to /usr/local. When $PYTHONHOME is set to a single
325 directory, its value replaces both ${prefix} and ${exec_prefix}.
326 To specify different values for these, set $PYTHONHOME to ${pre‐
327 fix}:${exec_prefix}.
328 PYTHONPATH
330 Augments the default search path for module files. The format
331 is the same as the shell's $PATH: one or more directory path‐
332 names separated by colons. Non-existent directories are
333 silently ignored. The default search path is installation de‐
334 pendent, but generally begins with ${prefix}/lib/python<version>
335 (see PYTHONHOME above). The default search path is always ap‐
336 pended to $PYTHONPATH. If a script argument is given, the di‐
337 rectory containing the script is inserted in the path in front
338 of $PYTHONPATH. The search path can be manipulated from within
339 a Python program as the variable sys.path.
340 PYTHONPLATLIBDIR
342 Override sys.platlibdir.
343 PYTHONSTARTUP
345 If this is the name of a readable file, the Python commands in
346 that file are executed before the first prompt is displayed in
347 interactive mode. The file is executed in the same name space
348 where interactive commands are executed so that objects defined
349 or imported in it can be used without qualification in the in‐
350 teractive session. You can also change the prompts sys.ps1 and
351 sys.ps2 in this file.
352 PYTHONOPTIMIZE
354 If this is set to a non-empty string it is equivalent to speci‐
355 fying the -O option. If set to an integer, it is equivalent to
356 specifying -O multiple times.
357 PYTHONDEBUG
359 If this is set to a non-empty string it is equivalent to speci‐
360 fying the -d option. If set to an integer, it is equivalent to
361 specifying -d multiple times.
362 PYTHONDONTWRITEBYTECODE
364 If this is set to a non-empty string it is equivalent to speci‐
365 fying the -B option (don't try to write .pyc files).
366 PYTHONINSPECT
368 If this is set to a non-empty string it is equivalent to speci‐
369 fying the -i option.
370 PYTHONIOENCODING
372 If this is set before running the interpreter, it overrides the
373 encoding used for stdin/stdout/stderr, in the syntax encoding‐
374 name:errorhandler The errorhandler part is optional and has the
375 same meaning as in str.encode. For stderr, the errorhandler
376 part is ignored; the handler will always be ´backslashreplace´.
377 PYTHONNOUSERSITE
379 If this is set to a non-empty string it is equivalent to speci‐
380 fying the -s option (Don't add the user site directory to
381 sys.path).
382 PYTHONUNBUFFERED
384 If this is set to a non-empty string it is equivalent to speci‐
385 fying the -u option.
386 PYTHONVERBOSE
388 If this is set to a non-empty string it is equivalent to speci‐
389 fying the -v option. If set to an integer, it is equivalent to
390 specifying -v multiple times.
391 PYTHONWARNINGS
393 If this is set to a comma-separated string it is equivalent to
394 specifying the -W option for each separate value.
395 PYTHONHASHSEED
397 If this variable is set to "random", a random value is used to
398 seed the hashes of str and bytes objects.
399 If PYTHONHASHSEED is set to an integer value, it is used as a
401 fixed seed for generating the hash() of the types covered by the
402 hash randomization. Its purpose is to allow repeatable hashing,
403 such as for selftests for the interpreter itself, or to allow a
404 cluster of python processes to share hash values.
405 The integer must be a decimal number in the range
407 [0,4294967295]. Specifying the value 0 will disable hash ran‐
408 domization.
409 PYTHONMALLOC
411 Set the Python memory allocators and/or install debug hooks. The
412 available memory allocators are malloc and pymalloc. The avail‐
413 able debug hooks are debug, malloc_debug, and pymalloc_debug.
414 When Python is compiled in debug mode, the default is pymal‐
416 loc_debug and the debug hooks are automatically used. Otherwise,
417 the default is pymalloc.
418 PYTHONMALLOCSTATS
420 If set to a non-empty string, Python will print statistics of
421 the pymalloc memory allocator every time a new pymalloc object
422 arena is created, and on shutdown.
423 This variable is ignored if the $PYTHONMALLOC environment vari‐
425 able is used to force the malloc(3) allocator of the C library,
426 or if Python is configured without pymalloc support.
427 PYTHONASYNCIODEBUG
429 If this environment variable is set to a non-empty string, en‐
430 able the debug mode of the asyncio module.
431 PYTHONTRACEMALLOC
433 If this environment variable is set to a non-empty string, start
434 tracing Python memory allocations using the tracemalloc module.
435 The value of the variable is the maximum number of frames stored
437 in a traceback of a trace. For example, PYTHONTRACEMALLOC=1
438 stores only the most recent frame.
439 PYTHONFAULTHANDLER
441 If this environment variable is set to a non-empty string,
442 faulthandler.enable() is called at startup: install a handler
443 for SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL signals to dump
444 the Python traceback.
445 This is equivalent to the -X faulthandler option.
447 PYTHONEXECUTABLE
449 If this environment variable is set, sys.argv[0] will be set to
450 its value instead of the value got through the C runtime. Only
451 works on Mac OS X.
452 PYTHONUSERBASE
454 Defines the user base directory, which is used to compute the
455 path of the user site-packages directory and Distutils installa‐
456 tion paths for python setup.py install --user.
457 PYTHONPROFILEIMPORTTIME
459 If this environment variable is set to a non-empty string,
460 Python will show how long each import takes. This is exactly
461 equivalent to setting -X importtime on the command line.
462 PYTHONBREAKPOINT
464 If this environment variable is set to 0, it disables the de‐
465 fault debugger. It can be set to the callable of your debugger
466 of choice.
467 Debug-mode variables
469 Setting these variables only has an effect in a debug build of Python,
470 that is, if Python was configured with the --with-pydebug build option.
471 PYTHONTHREADDEBUG
473 If this environment variable is set, Python will print threading
474 debug info. The feature is deprecated in Python 3.10 and will
475 be removed in Python 3.12.
476 PYTHONDUMPREFS
478 If this environment variable is set, Python will dump objects
479 and reference counts still alive after shutting down the inter‐
480 preter.
481
483 The Python Software Foundation: https://www.python.org/psf/
484
486 Main website: https://www.python.org/
487 Documentation: https://docs.python.org/
488 Developer resources: https://devguide.python.org/
489 Downloads: https://www.python.org/downloads/
490 Module repository: https://pypi.org/
491 Newsgroups: comp.lang.python, comp.lang.python.announce
492
494 Python is distributed under an Open Source license. See the file "LI‐
495 CENSE" in the Python source distribution for information on terms &
496 conditions for accessing and otherwise using Python and for a DIS‐
497 CLAIMER OF ALL WARRANTIES.
498 PYTHON(1)