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