| 1 |
.TH PYTHON "1" |
| 2 |
|
| 3 |
.\" To view this file while editing, run it through groff: |
| 4 |
.\" groff -Tascii -man python.man | less |
| 5 |
|
| 6 |
.SH NAME |
| 7 |
python \- an interpreted, interactive, object-oriented programming language |
| 8 |
.SH SYNOPSIS |
| 9 |
.B python |
| 10 |
[ |
| 11 |
.B \-B |
| 12 |
] |
| 13 |
[ |
| 14 |
.B \-b |
| 15 |
] |
| 16 |
[ |
| 17 |
.B \-d |
| 18 |
] |
| 19 |
[ |
| 20 |
.B \-E |
| 21 |
] |
| 22 |
[ |
| 23 |
.B \-h |
| 24 |
] |
| 25 |
[ |
| 26 |
.B \-i |
| 27 |
] |
| 28 |
[ |
| 29 |
.B \-I |
| 30 |
] |
| 31 |
.br |
| 32 |
[ |
| 33 |
.B \-m |
| 34 |
.I module-name |
| 35 |
] |
| 36 |
[ |
| 37 |
.B \-q |
| 38 |
] |
| 39 |
[ |
| 40 |
.B \-R |
| 41 |
] |
| 42 |
[ |
| 43 |
.B \-O |
| 44 |
] |
| 45 |
[ |
| 46 |
.B \-OO |
| 47 |
] |
| 48 |
[ |
| 49 |
.B \-P |
| 50 |
] |
| 51 |
[ |
| 52 |
.B \-s |
| 53 |
] |
| 54 |
[ |
| 55 |
.B \-S |
| 56 |
] |
| 57 |
[ |
| 58 |
.B \-u |
| 59 |
] |
| 60 |
.br |
| 61 |
[ |
| 62 |
.B \-v |
| 63 |
] |
| 64 |
[ |
| 65 |
.B \-V |
| 66 |
] |
| 67 |
[ |
| 68 |
.B \-W |
| 69 |
.I argument |
| 70 |
] |
| 71 |
[ |
| 72 |
.B \-x |
| 73 |
] |
| 74 |
[ |
| 75 |
.B \-X |
| 76 |
.I option |
| 77 |
] |
| 78 |
[ |
| 79 |
.B \-? |
| 80 |
] |
| 81 |
.br |
| 82 |
[ |
| 83 |
.B \-\-check-hash-based-pycs |
| 84 |
.I default |
| 85 |
| |
| 86 |
.I always |
| 87 |
| |
| 88 |
.I never |
| 89 |
] |
| 90 |
.br |
| 91 |
[ |
| 92 |
.B \-\-help |
| 93 |
] |
| 94 |
[ |
| 95 |
.B \-\-help\-env |
| 96 |
] |
| 97 |
[ |
| 98 |
.B \-\-help\-xoptions |
| 99 |
] |
| 100 |
[ |
| 101 |
.B \-\-help\-all |
| 102 |
] |
| 103 |
.br |
| 104 |
[ |
| 105 |
.B \-c |
| 106 |
.I command |
| 107 |
| |
| 108 |
.I script |
| 109 |
| |
| 110 |
\- |
| 111 |
] |
| 112 |
[ |
| 113 |
.I arguments |
| 114 |
] |
| 115 |
.SH DESCRIPTION |
| 116 |
Python is an interpreted, interactive, object-oriented programming |
| 117 |
language that combines remarkable power with very clear syntax. |
| 118 |
For an introduction to programming in Python, see the Python Tutorial. |
| 119 |
The Python Library Reference documents built-in and standard types, |
| 120 |
constants, functions and modules. |
| 121 |
Finally, the Python Reference Manual describes the syntax and |
| 122 |
semantics of the core language in (perhaps too) much detail. |
| 123 |
(These documents may be located via the |
| 124 |
.B "INTERNET RESOURCES" |
| 125 |
below; they may be installed on your system as well.) |
| 126 |
.PP |
| 127 |
Python's basic power can be extended with your own modules written in |
| 128 |
C or C++. |
| 129 |
On most systems such modules may be dynamically loaded. |
| 130 |
Python is also adaptable as an extension language for existing |
| 131 |
applications. |
| 132 |
See the internal documentation for hints. |
| 133 |
.PP |
| 134 |
Documentation for installed Python modules and packages can be |
| 135 |
viewed by running the |
| 136 |
.B pydoc |
| 137 |
program. |
| 138 |
.SH COMMAND LINE OPTIONS |
| 139 |
.TP |
| 140 |
.B \-B |
| 141 |
Don't write |
| 142 |
.I .pyc |
| 143 |
files on import. See also PYTHONDONTWRITEBYTECODE. |
| 144 |
.TP |
| 145 |
.B \-b |
| 146 |
Issue warnings about str(bytes_instance), str(bytearray_instance) |
| 147 |
and comparing bytes/bytearray with str. (\-bb: issue errors) |
| 148 |
.TP |
| 149 |
.BI "\-c " command |
| 150 |
Specify the command to execute (see next section). |
| 151 |
This terminates the option list (following options are passed as |
| 152 |
arguments to the command). |
| 153 |
.TP |
| 154 |
.BI "\-\-check\-hash\-based\-pycs " mode |
| 155 |
Configure how Python evaluates the up-to-dateness of hash-based .pyc files. |
| 156 |
.TP |
| 157 |
.B \-d |
| 158 |
Turn on parser debugging output (for expert only, depending on |
| 159 |
compilation options). |
| 160 |
.TP |
| 161 |
.B \-E |
| 162 |
Ignore environment variables like PYTHONPATH and PYTHONHOME that modify |
| 163 |
the behavior of the interpreter. |
| 164 |
.TP |
| 165 |
.B \-h ", " \-? ", "\-\-help |
| 166 |
Prints the usage for the interpreter executable and exits. |
| 167 |
.TP |
| 168 |
.B "\-\-help\-env" |
| 169 |
Prints help about Python-specific environment variables and exits. |
| 170 |
.TP |
| 171 |
.B "\-\-help\-xoptions" |
| 172 |
Prints help about implementation-specific \fB\-X\fP options and exits. |
| 173 |
.TP |
| 174 |
.TP |
| 175 |
.B "\-\-help\-all" |
| 176 |
Prints complete usage information and exits. |
| 177 |
.TP |
| 178 |
.B \-i |
| 179 |
When a script is passed as first argument or the \fB\-c\fP option is |
| 180 |
used, enter interactive mode after executing the script or the |
| 181 |
command. It does not read the $PYTHONSTARTUP file. This can be |
| 182 |
useful to inspect global variables or a stack trace when a script |
| 183 |
raises an exception. |
| 184 |
.TP |
| 185 |
.B \-I |
| 186 |
Run Python in isolated mode. This also implies \fB\-E\fP, \fB\-P\fP and \fB\-s\fP. In |
| 187 |
isolated mode sys.path contains neither the script's directory nor the user's |
| 188 |
site\-packages directory. All PYTHON* environment variables are ignored, too. |
| 189 |
Further restrictions may be imposed to prevent the user from injecting |
| 190 |
malicious code. |
| 191 |
.TP |
| 192 |
.BI "\-m " module-name |
| 193 |
Searches |
| 194 |
.I sys.path |
| 195 |
for the named module and runs the corresponding |
| 196 |
.I .py |
| 197 |
file as a script. This terminates the option list (following options |
| 198 |
are passed as arguments to the module). |
| 199 |
.TP |
| 200 |
.B \-O |
| 201 |
Remove assert statements and any code conditional on the value of |
| 202 |
__debug__; augment the filename for compiled (bytecode) files by |
| 203 |
adding .opt-1 before the .pyc extension. |
| 204 |
.TP |
| 205 |
.B \-OO |
| 206 |
Do \fB\-O\fP and also discard docstrings; change the filename for |
| 207 |
compiled (bytecode) files by adding .opt-2 before the .pyc extension. |
| 208 |
.TP |
| 209 |
.B \-P |
| 210 |
Don't automatically prepend a potentially unsafe path to \fBsys.path\fP such |
| 211 |
as the current directory, the script's directory or an empty string. See also the |
| 212 |
\fBPYTHONSAFEPATH\fP environment variable. |
| 213 |
.TP |
| 214 |
.B \-q |
| 215 |
Do not print the version and copyright messages. These messages are |
| 216 |
also suppressed in non-interactive mode. |
| 217 |
.TP |
| 218 |
.B \-R |
| 219 |
Turn on hash randomization. This option only has an effect if the |
| 220 |
\fBPYTHONHASHSEED\fR environment variable is set to \fB0\fR, since hash |
| 221 |
randomization is enabled by default. |
| 222 |
.TP |
| 223 |
.B \-s |
| 224 |
Don't add user site directory to sys.path. |
| 225 |
.TP |
| 226 |
.B \-S |
| 227 |
Disable the import of the module |
| 228 |
.I site |
| 229 |
and the site-dependent manipulations of |
| 230 |
.I sys.path |
| 231 |
that it entails. Also disable these manipulations if |
| 232 |
.I site |
| 233 |
is explicitly imported later. |
| 234 |
.TP |
| 235 |
.B \-u |
| 236 |
Force the stdout and stderr streams to be unbuffered. |
| 237 |
This option has no effect on the stdin stream. |
| 238 |
.TP |
| 239 |
.B \-v |
| 240 |
Print a message each time a module is initialized, showing the place |
| 241 |
(filename or built-in module) from which it is loaded. When given |
| 242 |
twice, print a message for each file that is checked for when |
| 243 |
searching for a module. Also provides information on module cleanup |
| 244 |
at exit. |
| 245 |
.TP |
| 246 |
.B \-V ", " \-\-version |
| 247 |
Prints the Python version number of the executable and exits. When given |
| 248 |
twice, print more information about the build. |
| 249 |
|
| 250 |
.TP |
| 251 |
.BI "\-W " argument |
| 252 |
Warning control. Python's warning machinery by default prints warning messages |
| 253 |
to |
| 254 |
.IR sys.stderr . |
| 255 |
|
| 256 |
The simplest settings apply a particular action unconditionally to all warnings |
| 257 |
emitted by a process (even those that are otherwise ignored by default): |
| 258 |
|
| 259 |
-Wdefault # Warn once per call location |
| 260 |
-Werror # Convert to exceptions |
| 261 |
-Walways # Warn every time |
| 262 |
-Wall # Same as -Walways |
| 263 |
-Wmodule # Warn once per calling module |
| 264 |
-Wonce # Warn once per Python process |
| 265 |
-Wignore # Never warn |
| 266 |
|
| 267 |
The action names can be abbreviated as desired and the interpreter will resolve |
| 268 |
them to the appropriate action name. For example, |
| 269 |
.B \-Wi |
| 270 |
is the same as |
| 271 |
.B \-Wignore . |
| 272 |
|
| 273 |
The full form of argument is: |
| 274 |
.IB action:message:category:module:lineno |
| 275 |
|
| 276 |
Empty fields match all values; trailing empty fields may be omitted. For |
| 277 |
example |
| 278 |
.B \-W ignore::DeprecationWarning |
| 279 |
ignores all DeprecationWarning warnings. |
| 280 |
|
| 281 |
The |
| 282 |
.I action |
| 283 |
field is as explained above but only applies to warnings that match |
| 284 |
the remaining fields. |
| 285 |
|
| 286 |
The |
| 287 |
.I message |
| 288 |
field must match the whole printed warning message; this match is |
| 289 |
case-insensitive. |
| 290 |
|
| 291 |
The |
| 292 |
.I category |
| 293 |
field matches the warning category (ex: "DeprecationWarning"). This must be a |
| 294 |
class name; the match test whether the actual warning category of the message |
| 295 |
is a subclass of the specified warning category. |
| 296 |
|
| 297 |
The |
| 298 |
.I module |
| 299 |
field matches the (fully-qualified) module name; this match is case-sensitive. |
| 300 |
|
| 301 |
The |
| 302 |
.I lineno |
| 303 |
field matches the line number, where zero matches all line numbers and is thus |
| 304 |
equivalent to an omitted line number. |
| 305 |
|
| 306 |
Multiple |
| 307 |
.B \-W |
| 308 |
options can be given; when a warning matches more than one option, the action |
| 309 |
for the last matching option is performed. Invalid |
| 310 |
.B \-W |
| 311 |
options are ignored (though, a warning message is printed about invalid options |
| 312 |
when the first warning is issued). |
| 313 |
|
| 314 |
Warnings can also be controlled using the |
| 315 |
.B PYTHONWARNINGS |
| 316 |
environment variable and from within a Python program using the warnings |
| 317 |
module. For example, the warnings.filterwarnings() function can be used to use |
| 318 |
a regular expression on the warning message. |
| 319 |
|
| 320 |
.TP |
| 321 |
.BI "\-X " option |
| 322 |
Set implementation-specific option. The following options are available: |
| 323 |
|
| 324 |
\fB\-X cpu_count=\fIN\fR: override the return value of \fIos.cpu_count()\fR; |
| 325 |
\fB\-X cpu_count=default\fR cancels overriding; also \fBPYTHON_CPU_COUNT\fI |
| 326 |
|
| 327 |
\fB\-X dev\fR: enable CPython's "development mode", introducing additional |
| 328 |
runtime checks which are too expensive to be enabled by default. It |
| 329 |
will not be more verbose than the default if the code is correct: new |
| 330 |
warnings are only emitted when an issue is detected. Effect of the |
| 331 |
developer mode: |
| 332 |
* Add default warning filter, as \fB\-W default\fR |
| 333 |
* Install debug hooks on memory allocators: see the |
| 334 |
PyMem_SetupDebugHooks() C function |
| 335 |
* Enable the faulthandler module to dump the Python traceback on a |
| 336 |
crash |
| 337 |
* Enable asyncio debug mode |
| 338 |
* Set the dev_mode attribute of sys.flags to True |
| 339 |
* io.IOBase destructor logs close() exceptions |
| 340 |
|
| 341 |
\fB\-X importtime\fR: show how long each import takes. It shows module name, |
| 342 |
cumulative time (including nested imports) and self time (excluding |
| 343 |
nested imports). Note that its output may be broken in multi-threaded |
| 344 |
application. Typical usage is |
| 345 |
\fBpython3 \-X importtime \-c 'import asyncio'\fR |
| 346 |
|
| 347 |
\fB\-X faulthandler\fR: enable faulthandler |
| 348 |
|
| 349 |
\fB\-X frozen_modules=\fR[\fBon\fR|\fBoff\fR]: whether or not frozen modules |
| 350 |
should be used. |
| 351 |
The default is "on" (or "off" if you are running a local build). |
| 352 |
|
| 353 |
\fB\-X gil=\fR[\fB0\fR|\fB1\fR]: enable (1) or disable (0) the GIL; also |
| 354 |
\fBPYTHON_GIL\fR |
| 355 |
Only available in builds configured with \fB\-\-disable\-gil\fR. |
| 356 |
|
| 357 |
\fB\-X int_max_str_digits=\fInumber\fR: limit the size of int<->str conversions. |
| 358 |
This helps avoid denial of service attacks when parsing untrusted data. |
| 359 |
The default is sys.int_info.default_max_str_digits. 0 disables. |
| 360 |
|
| 361 |
\fB\-X no_debug_ranges\fR: disable the inclusion of the tables mapping extra |
| 362 |
location information (end line, start column offset and end column |
| 363 |
offset) to every instruction in code objects. This is useful when |
| 364 |
smaller code objects and pyc files are desired as well as suppressing |
| 365 |
the extra visual location indicators when the interpreter displays |
| 366 |
tracebacks. |
| 367 |
|
| 368 |
\fB\-X perf\fR: support the Linux "perf" profiler; also \fBPYTHONPERFSUPPORT=1\fR |
| 369 |
|
| 370 |
\fB\-X perf_jit\fR: support the Linux "perf" profiler with DWARF support; |
| 371 |
also \fBPYTHON_PERF_JIT_SUPPORT=1\fR |
| 372 |
|
| 373 |
\fB\-X presite=\fIMOD\fR: import this module before site; also \fBPYTHON_PRESITE\fR |
| 374 |
This only works on debug builds. |
| 375 |
|
| 376 |
\fB\-X pycache_prefix=\fIPATH\fR: enable writing .pyc files to a parallel |
| 377 |
tree rooted at the given directory instead of to the code tree. |
| 378 |
|
| 379 |
\fB\-X showrefcount\fR: output the total reference count and number of used |
| 380 |
memory blocks when the program finishes or after each statement in the |
| 381 |
interactive interpreter. This only works on debug builds |
| 382 |
|
| 383 |
\fB\-X tracemalloc\fR: start tracing Python memory allocations using the |
| 384 |
tracemalloc module. By default, only the most recent frame is stored in a |
| 385 |
traceback of a trace. Use \-X tracemalloc=NFRAME to start tracing with a |
| 386 |
traceback limit of NFRAME frames |
| 387 |
|
| 388 |
\fB\-X utf8\fR: enable UTF-8 mode for operating system interfaces, |
| 389 |
overriding the default locale-aware mode. \fB\-X utf8=0\fR explicitly |
| 390 |
disables UTF-8 mode (even when it would otherwise activate |
| 391 |
automatically). See \fBPYTHONUTF8\fR for more details |
| 392 |
|
| 393 |
\fB\-X warn_default_encoding\fR: enable opt-in EncodingWarning for 'encoding=None' |
| 394 |
|
| 395 |
.TP |
| 396 |
.B \-x |
| 397 |
Skip the first line of the source. This is intended for a DOS |
| 398 |
specific hack only. Warning: the line numbers in error messages will |
| 399 |
be off by one! |
| 400 |
.SH INTERPRETER INTERFACE |
| 401 |
The interpreter interface resembles that of the UNIX shell: when |
| 402 |
called with standard input connected to a tty device, it prompts for |
| 403 |
commands and executes them until an EOF is read; when called with a |
| 404 |
file name argument or with a file as standard input, it reads and |
| 405 |
executes a |
| 406 |
.I script |
| 407 |
from that file; |
| 408 |
when called with |
| 409 |
.B \-c |
| 410 |
.IR command , |
| 411 |
it executes the Python statement(s) given as |
| 412 |
.IR command . |
| 413 |
Here |
| 414 |
.I command |
| 415 |
may contain multiple statements separated by newlines. |
| 416 |
Leading whitespace is significant in Python statements! |
| 417 |
In non-interactive mode, the entire input is parsed before it is |
| 418 |
executed. |
| 419 |
.PP |
| 420 |
If available, the script name and additional arguments thereafter are |
| 421 |
passed to the script in the Python variable |
| 422 |
.IR sys.argv , |
| 423 |
which is a list of strings (you must first |
| 424 |
.I import sys |
| 425 |
to be able to access it). |
| 426 |
If no script name is given, |
| 427 |
.I sys.argv[0] |
| 428 |
is an empty string; if |
| 429 |
.B \-c |
| 430 |
is used, |
| 431 |
.I sys.argv[0] |
| 432 |
contains the string |
| 433 |
.I '\-c'. |
| 434 |
Note that options interpreted by the Python interpreter itself |
| 435 |
are not placed in |
| 436 |
.IR sys.argv . |
| 437 |
.PP |
| 438 |
In interactive mode, the primary prompt is `>>>'; the second prompt |
| 439 |
(which appears when a command is not complete) is `...'. |
| 440 |
The prompts can be changed by assignment to |
| 441 |
.I sys.ps1 |
| 442 |
or |
| 443 |
.IR sys.ps2 . |
| 444 |
The interpreter quits when it reads an EOF at a prompt. |
| 445 |
When an unhandled exception occurs, a stack trace is printed and |
| 446 |
control returns to the primary prompt; in non-interactive mode, the |
| 447 |
interpreter exits after printing the stack trace. |
| 448 |
The interrupt signal raises the |
| 449 |
.I Keyboard\%Interrupt |
| 450 |
exception; other UNIX signals are not caught (except that SIGPIPE is |
| 451 |
sometimes ignored, in favor of the |
| 452 |
.I IOError |
| 453 |
exception). Error messages are written to stderr. |
| 454 |
.SH FILES AND DIRECTORIES |
| 455 |
These are subject to difference depending on local installation |
| 456 |
conventions; ${prefix} and ${exec_prefix} are installation-dependent |
| 457 |
and should be interpreted as for GNU software; they may be the same. |
| 458 |
On Debian GNU/{Hurd,Linux} the default for both is \fI/usr\fP. |
| 459 |
.IP \fI${exec_prefix}/bin/python\fP |
| 460 |
Recommended location of the interpreter. |
| 461 |
.PP |
| 462 |
.I ${prefix}/lib/python<version> |
| 463 |
.br |
| 464 |
.I ${exec_prefix}/lib/python<version> |
| 465 |
.RS |
| 466 |
Recommended locations of the directories containing the standard |
| 467 |
modules. |
| 468 |
.RE |
| 469 |
.PP |
| 470 |
.I ${prefix}/include/python<version> |
| 471 |
.br |
| 472 |
.I ${exec_prefix}/include/python<version> |
| 473 |
.RS |
| 474 |
Recommended locations of the directories containing the include files |
| 475 |
needed for developing Python extensions and embedding the |
| 476 |
interpreter. |
| 477 |
.RE |
| 478 |
.SH ENVIRONMENT VARIABLES |
| 479 |
.IP PYTHONASYNCIODEBUG |
| 480 |
If this environment variable is set to a non-empty string, enable the debug |
| 481 |
mode of the asyncio module. |
| 482 |
.IP PYTHON_BASIC_REPL |
| 483 |
If this variable is set to any value, the interpreter will not attempt to |
| 484 |
load the Python-based REPL that requires curses and readline, and will instead |
| 485 |
use the traditional parser-based REPL. |
| 486 |
.IP PYTHONBREAKPOINT |
| 487 |
If this environment variable is set to 0, it disables the default debugger. It |
| 488 |
can be set to the callable of your debugger of choice. |
| 489 |
.IP PYTHONCOERCECLOCALE |
| 490 |
If set to the value 0, causes the main Python command line application to skip |
| 491 |
coercing the legacy ASCII-based C and POSIX locales to a more capable UTF-8 |
| 492 |
based alternative. |
| 493 |
.IP PYTHON_COLORS |
| 494 |
If this variable is set to 1, the interpreter will colorize various kinds of |
| 495 |
output. Setting it to 0 deactivates this behavior. |
| 496 |
.IP PYTHON_CPU_COUNT |
| 497 |
If this variable is set to a positive integer, it overrides the return |
| 498 |
values of \fIos.cpu_count\fR and \fIos.process_cpu_count\fR. |
| 499 |
.IP |
| 500 |
See also the \fB\-X cpu_count\fR option. |
| 501 |
.IP PYTHONDEBUG |
| 502 |
If this is set to a non-empty string it is equivalent to specifying |
| 503 |
the \fB\-d\fP option. If set to an integer, it is equivalent to |
| 504 |
specifying \fB\-d\fP multiple times. |
| 505 |
.IP PYTHONEXECUTABLE |
| 506 |
If this environment variable is set, |
| 507 |
.IB sys.argv[0] |
| 508 |
will be set to its value instead of the value got through the C runtime. Only |
| 509 |
works on Mac OS X. |
| 510 |
.IP PYTHONFAULTHANDLER |
| 511 |
If this environment variable is set to a non-empty string, |
| 512 |
.IR faulthandler.enable() |
| 513 |
is called at startup: install a handler for SIGSEGV, SIGFPE, SIGABRT, SIGBUS |
| 514 |
and SIGILL signals to dump the Python traceback. |
| 515 |
.IP |
| 516 |
This is equivalent to the \fB\-X faulthandler\fP option. |
| 517 |
.IP PYTHON_FROZEN_MODULES |
| 518 |
If this variable is set to \fBon\fR or \fBoff\fR, it determines whether or not |
| 519 |
frozen modules are ignored by the import machinery. A value of \fBon\fR means |
| 520 |
they get imported and \fBoff\fR means they are ignored. The default is \fBon\fR |
| 521 |
for non-debug builds (the normal case) and \fBoff\fR for debug builds. |
| 522 |
.IP |
| 523 |
See also the \fB\-X frozen_modules\fR option. |
| 524 |
.IP PYTHON_GIL |
| 525 |
If this variable is set to 1, the global interpreter lock (GIL) will be forced |
| 526 |
on. Setting it to 0 forces the GIL off. Only available in builds configured |
| 527 |
with \fB\-\-disable\-gil\fP. |
| 528 |
.IP |
| 529 |
This is equivalent to the \fB\-X gil\fR option. |
| 530 |
.IP PYTHON_HISTORY |
| 531 |
This environment variable can be used to set the location of a history file |
| 532 |
(on Unix, it is \fI~/.python_history\fP by default). |
| 533 |
.IP PYTHONNODEBUGRANGES |
| 534 |
If this variable is set, it disables the inclusion of the tables mapping |
| 535 |
extra location information (end line, start column offset and end column |
| 536 |
offset) to every instruction in code objects. This is useful when smaller code |
| 537 |
objects and pyc files are desired as well as suppressing the extra visual |
| 538 |
location indicators when the interpreter displays tracebacks. |
| 539 |
.IP PYTHONDONTWRITEBYTECODE |
| 540 |
If this is set to a non-empty string it is equivalent to specifying |
| 541 |
the \fB\-B\fP option (don't try to write |
| 542 |
.I .pyc |
| 543 |
files). |
| 544 |
.IP PYTHONDEVMODE |
| 545 |
If this environment variable is set to a non-empty string, enable Python's |
| 546 |
"development mode", introducing additional runtime checks that are too |
| 547 |
expensive to be enabled by default. |
| 548 |
.IP |
| 549 |
This is equivalent to the \fB\-X dev\fR option. |
| 550 |
.IP PYTHONHASHSEED |
| 551 |
If this variable is set to "random", a random value is used to seed the hashes |
| 552 |
of str and bytes objects. |
| 553 |
|
| 554 |
If PYTHONHASHSEED is set to an integer value, it is used as a fixed seed for |
| 555 |
generating the hash() of the types covered by the hash randomization. Its |
| 556 |
purpose is to allow repeatable hashing, such as for selftests for the |
| 557 |
interpreter itself, or to allow a cluster of python processes to share hash |
| 558 |
values. |
| 559 |
|
| 560 |
The integer must be a decimal number in the range [0,4294967295]. Specifying |
| 561 |
the value 0 will disable hash randomization. |
| 562 |
.IP PYTHONHOME |
| 563 |
Change the location of the standard Python libraries. By default, the |
| 564 |
libraries are searched in ${prefix}/lib/python<version> and |
| 565 |
${exec_prefix}/lib/python<version>, where ${prefix} and ${exec_prefix} |
| 566 |
are installation-dependent directories, both defaulting to |
| 567 |
\fI/usr/local\fP. When $PYTHONHOME is set to a single directory, its value |
| 568 |
replaces both ${prefix} and ${exec_prefix}. To specify different values |
| 569 |
for these, set $PYTHONHOME to ${prefix}:${exec_prefix}. |
| 570 |
.IP PYTHONINSPECT |
| 571 |
If this is set to a non-empty string it is equivalent to specifying |
| 572 |
the \fB\-i\fP option. |
| 573 |
.IP PYTHONINTMAXSTRDIGITS |
| 574 |
Limit the maximum digit characters in an int value |
| 575 |
when converting from a string and when converting an int back to a str. |
| 576 |
A value of 0 disables the limit. Conversions to or from bases 2, 4, 8, |
| 577 |
16, and 32 are never limited. |
| 578 |
.IP |
| 579 |
This is equivalent to the \fB\-X int_max_str_digits=\fINUMBER\fR option. |
| 580 |
.IP PYTHONIOENCODING |
| 581 |
If this is set before running the interpreter, it overrides the encoding used |
| 582 |
for stdin/stdout/stderr, in the syntax |
| 583 |
.IB encodingname ":" errorhandler |
| 584 |
The |
| 585 |
.IB errorhandler |
| 586 |
part is optional and has the same meaning as in str.encode. For stderr, the |
| 587 |
.IB errorhandler |
| 588 |
part is ignored; the handler will always be \'backslashreplace\'. |
| 589 |
.IP PYTHONMALLOC |
| 590 |
Set the Python memory allocators and/or install debug hooks. The available |
| 591 |
memory allocators are |
| 592 |
.IR malloc |
| 593 |
and |
| 594 |
.IR pymalloc . |
| 595 |
The available debug hooks are |
| 596 |
.IR debug , |
| 597 |
.IR malloc_debug , |
| 598 |
and |
| 599 |
.IR pymalloc_debug . |
| 600 |
.IP |
| 601 |
When Python is compiled in debug mode, the default is |
| 602 |
.IR pymalloc_debug |
| 603 |
and the debug hooks are automatically used. Otherwise, the default is |
| 604 |
.IR pymalloc . |
| 605 |
.IP PYTHONMALLOCSTATS |
| 606 |
If set to a non-empty string, Python will print statistics of the pymalloc |
| 607 |
memory allocator every time a new pymalloc object arena is created, and on |
| 608 |
shutdown. |
| 609 |
.IP |
| 610 |
This variable is ignored if the |
| 611 |
.RB $ PYTHONMALLOC |
| 612 |
environment variable is used to force the |
| 613 |
.BR malloc (3) |
| 614 |
allocator of the C library, or if Python is configured without pymalloc support. |
| 615 |
.IP PYTHONNOUSERSITE |
| 616 |
If this is set to a non-empty string it is equivalent to specifying the |
| 617 |
\fB\-s\fP option (Don't add the user site directory to sys.path). |
| 618 |
.IP PYTHONOPTIMIZE |
| 619 |
If this is set to a non-empty string it is equivalent to specifying |
| 620 |
the \fB\-O\fP option. If set to an integer, it is equivalent to |
| 621 |
specifying \fB\-O\fP multiple times. |
| 622 |
.IP PYTHONPATH |
| 623 |
Augments the default search path for module files. |
| 624 |
The format is the same as the shell's $PATH: one or more directory |
| 625 |
pathnames separated by colons. |
| 626 |
Non-existent directories are silently ignored. |
| 627 |
The default search path is installation dependent, but generally |
| 628 |
begins with ${prefix}/lib/python<version> (see PYTHONHOME above). |
| 629 |
The default search path is always appended to $PYTHONPATH. |
| 630 |
If a script argument is given, the directory containing the script is |
| 631 |
inserted in the path in front of $PYTHONPATH. |
| 632 |
The search path can be manipulated from within a Python program as the |
| 633 |
variable |
| 634 |
.IR sys.path . |
| 635 |
.IP PYTHON_PERF_JIT_SUPPORT |
| 636 |
If this variable is set to a nonzero value, it enables support for |
| 637 |
the Linux perf profiler so Python calls can be detected by it using DWARF |
| 638 |
information. |
| 639 |
Setting to 0 disables. |
| 640 |
.IP |
| 641 |
See also the \fB\-X perf_jit\fR option. |
| 642 |
.IP PYTHONPERFSUPPORT |
| 643 |
If this variable is set to a nonzero value, it enables support for |
| 644 |
the Linux perf profiler so Python calls can be detected by it. |
| 645 |
Setting to 0 disables. |
| 646 |
.IP |
| 647 |
See also the \fB\-X perf\fR option. |
| 648 |
.IP PYTHONPLATLIBDIR |
| 649 |
Override sys.platlibdir. |
| 650 |
.IP PYTHONPROFILEIMPORTTIME |
| 651 |
If this environment variable is set to a non-empty string, Python will |
| 652 |
show how long each import takes. This is exactly equivalent to setting |
| 653 |
\fB\-X importtime\fP on the command line. |
| 654 |
.IP PYTHONPYCACHEPREFIX |
| 655 |
If this is set, Python will write \fB.pyc\fR files in a mirror directory tree |
| 656 |
at this path, instead of in \fB__pycache__\fR directories within the source |
| 657 |
tree. |
| 658 |
.IP |
| 659 |
This is equivalent to specifying the \fB\-X pycache_prefix=\fIPATH\fR option. |
| 660 |
.IP PYTHONSAFEPATH |
| 661 |
If this is set to a non-empty string, don't automatically prepend a potentially |
| 662 |
unsafe path to \fBsys.path\fP such as the current directory, the script's |
| 663 |
directory or an empty string. See also the \fB\-P\fP option. |
| 664 |
.IP PYTHONSTARTUP |
| 665 |
If this is the name of a readable file, the Python commands in that |
| 666 |
file are executed before the first prompt is displayed in interactive |
| 667 |
mode. |
| 668 |
The file is executed in the same name space where interactive commands |
| 669 |
are executed so that objects defined or imported in it can be used |
| 670 |
without qualification in the interactive session. |
| 671 |
You can also change the prompts |
| 672 |
.I sys.ps1 |
| 673 |
and |
| 674 |
.I sys.ps2 |
| 675 |
in this file. |
| 676 |
.IP PYTHONTRACEMALLOC |
| 677 |
If this environment variable is set to a non-empty string, start tracing |
| 678 |
Python memory allocations using the tracemalloc module. |
| 679 |
.IP |
| 680 |
The value of the variable is the maximum number of frames stored in a |
| 681 |
traceback of a trace. For example, |
| 682 |
.IB PYTHONTRACEMALLOC=1 |
| 683 |
stores only the most recent frame. |
| 684 |
.IP PYTHONUNBUFFERED |
| 685 |
If this is set to a non-empty string it is equivalent to specifying |
| 686 |
the \fB\-u\fP option. |
| 687 |
.IP PYTHONUSERBASE |
| 688 |
Defines the user base directory, which is used to compute the path of the user |
| 689 |
.IR site\-packages |
| 690 |
directory and installation paths for |
| 691 |
.IR "python \-m pip install \-\-user" . |
| 692 |
.IP PYTHONUTF8 |
| 693 |
If set to 1, enable the Python "UTF-8 Mode". Setting to 0 disables. |
| 694 |
.IP PYTHONVERBOSE |
| 695 |
If this is set to a non-empty string it is equivalent to specifying |
| 696 |
the \fB\-v\fP option. If set to an integer, it is equivalent to |
| 697 |
specifying \fB\-v\fP multiple times. |
| 698 |
.IP PYTHONWARNDEFAULTENCODING |
| 699 |
If this environment variable is set to a non-empty string, issue a |
| 700 |
\fIEncodingWarning\fR when the locale-specific default encoding is used. |
| 701 |
.IP PYTHONWARNINGS |
| 702 |
If this is set to a comma-separated string it is equivalent to |
| 703 |
specifying the \fB\-W\fP option for each separate value. |
| 704 |
.SS Debug-mode variables |
| 705 |
Setting these variables only has an effect in a debug build of Python, that is, |
| 706 |
if Python was configured with the |
| 707 |
\fB\-\-with\-pydebug\fP build option. |
| 708 |
.IP PYTHONDUMPREFS |
| 709 |
If this environment variable is set, Python will dump objects and reference |
| 710 |
counts still alive after shutting down the interpreter. |
| 711 |
.IP PYTHONDUMPREFSFILE |
| 712 |
If set, Python will dump objects and reference counts still alive after |
| 713 |
shutting down the interpreter into a file under the path given as the value to |
| 714 |
this environment variable. |
| 715 |
.IP PYTHON_PRESITE |
| 716 |
If this variable is set to a module, that module will be imported |
| 717 |
early in the interpreter lifecycle, before the \fIsite\fR module is |
| 718 |
executed, and before the \fI__main__\fR module is created. |
| 719 |
This only works on debug builds. |
| 720 |
.IP |
| 721 |
This is equivalent to the \fB\-X presite=\fImodule\fR option. |
| 722 |
.SH AUTHOR |
| 723 |
The Python Software Foundation: https://www.python.org/psf/ |
| 724 |
.SH INTERNET RESOURCES |
| 725 |
Main website: https://www.python.org/ |
| 726 |
.br |
| 727 |
Documentation: https://docs.python.org/ |
| 728 |
.br |
| 729 |
Developer resources: https://devguide.python.org/ |
| 730 |
.br |
| 731 |
Downloads: https://www.python.org/downloads/ |
| 732 |
.br |
| 733 |
Module repository: https://pypi.org/ |
| 734 |
.br |
| 735 |
Newsgroups: comp.lang.python, comp.lang.python.announce |
| 736 |
.SH LICENSING |
| 737 |
Python is distributed under an Open Source license. See the file |
| 738 |
"LICENSE" in the Python source distribution for information on terms & |
| 739 |
conditions for accessing and otherwise using Python and for a |
| 740 |
DISCLAIMER OF ALL WARRANTIES. |