|
1 .. highlightlang:: none |
|
2 |
|
3 .. _using-on-general: |
|
4 |
|
5 Command line and environment |
|
6 ============================ |
|
7 |
|
8 The CPython interpreter scans the command line and the environment for various |
|
9 settings. |
|
10 |
|
11 .. note:: |
|
12 |
|
13 Other implementations' command line schemes may differ. See |
|
14 :ref:`implementations` for further resources. |
|
15 |
|
16 |
|
17 .. _using-on-cmdline: |
|
18 |
|
19 Command line |
|
20 ------------ |
|
21 |
|
22 When invoking Python, you may specify any of these options:: |
|
23 |
|
24 python [-dEiOQsStuUvxX3?] [-c command | -m module-name | script | - ] [args] |
|
25 |
|
26 The most common use case is, of course, a simple invocation of a script:: |
|
27 |
|
28 python myscript.py |
|
29 |
|
30 |
|
31 .. _using-on-interface-options: |
|
32 |
|
33 Interface options |
|
34 ~~~~~~~~~~~~~~~~~ |
|
35 |
|
36 The interpreter interface resembles that of the UNIX shell, but provides some |
|
37 additional methods of invocation: |
|
38 |
|
39 * When called with standard input connected to a tty device, it prompts for |
|
40 commands and executes them until an EOF (an end-of-file character, you can |
|
41 produce that with *Ctrl-D* on UNIX or *Ctrl-Z, Enter* on Windows) is read. |
|
42 * When called with a file name argument or with a file as standard input, it |
|
43 reads and executes a script from that file. |
|
44 * When called with a directory name argument, it reads and executes an |
|
45 appropriately named script from that directory. |
|
46 * When called with ``-c command``, it executes the Python statement(s) given as |
|
47 *command*. Here *command* may contain multiple statements separated by |
|
48 newlines. Leading whitespace is significant in Python statements! |
|
49 * When called with ``-m module-name``, the given module is located on the |
|
50 Python module path and executed as a script. |
|
51 |
|
52 In non-interactive mode, the entire input is parsed before it is executed. |
|
53 |
|
54 An interface option terminates the list of options consumed by the interpreter, |
|
55 all consecutive arguments will end up in :data:`sys.argv` -- note that the first |
|
56 element, subscript zero (``sys.argv[0]``), is a string reflecting the program's |
|
57 source. |
|
58 |
|
59 .. cmdoption:: -c <command> |
|
60 |
|
61 Execute the Python code in *command*. *command* can be one ore more |
|
62 statements separated by newlines, with significant leading whitespace as in |
|
63 normal module code. |
|
64 |
|
65 If this option is given, the first element of :data:`sys.argv` will be |
|
66 ``"-c"`` and the current directory will be added to the start of |
|
67 :data:`sys.path` (allowing modules in that directory to be imported as top |
|
68 level modules). |
|
69 |
|
70 |
|
71 .. cmdoption:: -m <module-name> |
|
72 |
|
73 Search :data:`sys.path` for the named module and execute its contents as |
|
74 the :mod:`__main__` module. |
|
75 |
|
76 Since the argument is a *module* name, you must not give a file extension |
|
77 (``.py``). The ``module-name`` should be a valid Python module name, but |
|
78 the implementation may not always enforce this (e.g. it may allow you to |
|
79 use a name that includes a hyphen). |
|
80 |
|
81 .. note:: |
|
82 |
|
83 This option cannot be used with builtin modules and extension modules |
|
84 written in C, since they do not have Python module files. However, it |
|
85 can still be used for precompiled modules, even if the original source |
|
86 file is not available. |
|
87 |
|
88 If this option is given, the first element of :data:`sys.argv` will be the |
|
89 full path to the module file. As with the :option:`-c` option, the current |
|
90 directory will be added to the start of :data:`sys.path`. |
|
91 |
|
92 Many standard library modules contain code that is invoked on their execution |
|
93 as a script. An example is the :mod:`timeit` module:: |
|
94 |
|
95 python -mtimeit -s 'setup here' 'benchmarked code here' |
|
96 python -mtimeit -h # for details |
|
97 |
|
98 .. seealso:: |
|
99 :func:`runpy.run_module` |
|
100 The actual implementation of this feature. |
|
101 |
|
102 :pep:`338` -- Executing modules as scripts |
|
103 |
|
104 .. versionadded:: 2.4 |
|
105 |
|
106 .. versionchanged:: 2.5 |
|
107 The named module can now be located inside a package. |
|
108 |
|
109 |
|
110 .. describe:: - |
|
111 |
|
112 Read commands from standard input (:data:`sys.stdin`). If standard input is |
|
113 a terminal, :option:`-i` is implied. |
|
114 |
|
115 If this option is given, the first element of :data:`sys.argv` will be |
|
116 ``"-"`` and the current directory will be added to the start of |
|
117 :data:`sys.path`. |
|
118 |
|
119 |
|
120 .. describe:: <script> |
|
121 |
|
122 Execute the Python code contained in *script*, which must be a filesystem |
|
123 path (absolute or relative) referring to either a Python file, a directory |
|
124 containing a ``__main__.py`` file, or a zipfile containing a |
|
125 ``__main__.py`` file. |
|
126 |
|
127 If this option is given, the first element of :data:`sys.argv` will be the |
|
128 script name as given on the command line. |
|
129 |
|
130 If the script name refers directly to a Python file, the directory |
|
131 containing that file is added to the start of :data:`sys.path`, and the |
|
132 file is executed as the :mod:`__main__` module. |
|
133 |
|
134 If the script name refers to a directory or zipfile, the script name is |
|
135 added to the start of :data:`sys.path` and the ``__main__.py`` file in |
|
136 that location is executed as the :mod:`__main__` module. |
|
137 |
|
138 .. versionchanged:: 2.5 |
|
139 Directories and zipfiles containing a ``__main__.py`` file at the top |
|
140 level are now considered valid Python scripts. |
|
141 |
|
142 If no interface option is given, :option:`-i` is implied, ``sys.argv[0]`` is |
|
143 an empty string (``""``) and the current directory will be added to the |
|
144 start of :data:`sys.path`. |
|
145 |
|
146 .. seealso:: :ref:`tut-invoking` |
|
147 |
|
148 |
|
149 Generic options |
|
150 ~~~~~~~~~~~~~~~ |
|
151 |
|
152 .. cmdoption:: -? |
|
153 -h |
|
154 --help |
|
155 |
|
156 Print a short description of all command line options. |
|
157 |
|
158 .. versionchanged:: 2.5 |
|
159 The ``--help`` variant. |
|
160 |
|
161 |
|
162 .. cmdoption:: -V |
|
163 --version |
|
164 |
|
165 Print the Python version number and exit. Example output could be:: |
|
166 |
|
167 Python 2.5.1 |
|
168 |
|
169 .. versionchanged:: 2.5 |
|
170 The ``--version`` variant. |
|
171 |
|
172 |
|
173 Miscellaneous options |
|
174 ~~~~~~~~~~~~~~~~~~~~~ |
|
175 |
|
176 .. cmdoption:: -B |
|
177 |
|
178 If given, Python won't try to write ``.pyc`` or ``.pyo`` files on the |
|
179 import of source modules. See also :envvar:`PYTHONDONTWRITEBYTECODE`. |
|
180 |
|
181 .. versionadded:: 2.6 |
|
182 |
|
183 |
|
184 .. cmdoption:: -d |
|
185 |
|
186 Turn on parser debugging output (for wizards only, depending on compilation |
|
187 options). See also :envvar:`PYTHONDEBUG`. |
|
188 |
|
189 |
|
190 .. cmdoption:: -E |
|
191 |
|
192 Ignore all :envvar:`PYTHON*` environment variables, e.g. |
|
193 :envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set. |
|
194 |
|
195 .. versionadded:: 2.2 |
|
196 |
|
197 |
|
198 .. cmdoption:: -i |
|
199 |
|
200 When a script is passed as first argument or the :option:`-c` option is used, |
|
201 enter interactive mode after executing the script or the command, even when |
|
202 :data:`sys.stdin` does not appear to be a terminal. The |
|
203 :envvar:`PYTHONSTARTUP` file is not read. |
|
204 |
|
205 This can be useful to inspect global variables or a stack trace when a script |
|
206 raises an exception. See also :envvar:`PYTHONINSPECT`. |
|
207 |
|
208 |
|
209 .. cmdoption:: -O |
|
210 |
|
211 Turn on basic optimizations. This changes the filename extension for |
|
212 compiled (:term:`bytecode`) files from ``.pyc`` to ``.pyo``. See also |
|
213 :envvar:`PYTHONOPTIMIZE`. |
|
214 |
|
215 |
|
216 .. cmdoption:: -OO |
|
217 |
|
218 Discard docstrings in addition to the :option:`-O` optimizations. |
|
219 |
|
220 |
|
221 .. cmdoption:: -Q <arg> |
|
222 |
|
223 Division control. The argument must be one of the following: |
|
224 |
|
225 ``old`` |
|
226 division of int/int and long/long return an int or long (*default*) |
|
227 ``new`` |
|
228 new division semantics, i.e. division of int/int and long/long returns a |
|
229 float |
|
230 ``warn`` |
|
231 old division semantics with a warning for int/int and long/long |
|
232 ``warnall`` |
|
233 old division semantics with a warning for all uses of the division operator |
|
234 |
|
235 .. seealso:: |
|
236 :file:`Tools/scripts/fixdiv.py` |
|
237 for a use of ``warnall`` |
|
238 |
|
239 :pep:`238` -- Changing the division operator |
|
240 |
|
241 |
|
242 .. cmdoption:: -s |
|
243 |
|
244 Don't add user site directory to sys.path |
|
245 |
|
246 .. versionadded:: 2.6 |
|
247 |
|
248 .. seealso:: |
|
249 |
|
250 :pep:`370` -- Per user site-packages directory |
|
251 |
|
252 |
|
253 .. cmdoption:: -S |
|
254 |
|
255 Disable the import of the module :mod:`site` and the site-dependent |
|
256 manipulations of :data:`sys.path` that it entails. |
|
257 |
|
258 |
|
259 .. cmdoption:: -t |
|
260 |
|
261 Issue a warning when a source file mixes tabs and spaces for indentation in a |
|
262 way that makes it depend on the worth of a tab expressed in spaces. Issue an |
|
263 error when the option is given twice (:option:`-tt`). |
|
264 |
|
265 |
|
266 .. cmdoption:: -u |
|
267 |
|
268 Force stdin, stdout and stderr to be totally unbuffered. On systems where it |
|
269 matters, also put stdin, stdout and stderr in binary mode. |
|
270 |
|
271 Note that there is internal buffering in :meth:`file.readlines` and |
|
272 :ref:`bltin-file-objects` (``for line in sys.stdin``) which is not influenced |
|
273 by this option. To work around this, you will want to use |
|
274 :meth:`file.readline` inside a ``while 1:`` loop. |
|
275 |
|
276 See also :envvar:`PYTHONUNBUFFERED`. |
|
277 |
|
278 |
|
279 .. XXX should the -U option be documented? |
|
280 |
|
281 .. cmdoption:: -v |
|
282 |
|
283 Print a message each time a module is initialized, showing the place |
|
284 (filename or built-in module) from which it is loaded. When given twice |
|
285 (:option:`-vv`), print a message for each file that is checked for when |
|
286 searching for a module. Also provides information on module cleanup at exit. |
|
287 See also :envvar:`PYTHONVERBOSE`. |
|
288 |
|
289 |
|
290 .. cmdoption:: -W arg |
|
291 |
|
292 Warning control. Python's warning machinery by default prints warning |
|
293 messages to :data:`sys.stderr`. A typical warning message has the following |
|
294 form:: |
|
295 |
|
296 file:line: category: message |
|
297 |
|
298 By default, each warning is printed once for each source line where it |
|
299 occurs. This option controls how often warnings are printed. |
|
300 |
|
301 Multiple :option:`-W` options may be given; when a warning matches more than |
|
302 one option, the action for the last matching option is performed. Invalid |
|
303 :option:`-W` options are ignored (though, a warning message is printed about |
|
304 invalid options when the first warning is issued). |
|
305 |
|
306 Warnings can also be controlled from within a Python program using the |
|
307 :mod:`warnings` module. |
|
308 |
|
309 The simplest form of argument is one of the following action strings (or a |
|
310 unique abbreviation): |
|
311 |
|
312 ``ignore`` |
|
313 Ignore all warnings. |
|
314 ``default`` |
|
315 Explicitly request the default behavior (printing each warning once per |
|
316 source line). |
|
317 ``all`` |
|
318 Print a warning each time it occurs (this may generate many messages if a |
|
319 warning is triggered repeatedly for the same source line, such as inside a |
|
320 loop). |
|
321 ``module`` |
|
322 Print each warning only only the first time it occurs in each module. |
|
323 ``once`` |
|
324 Print each warning only the first time it occurs in the program. |
|
325 ``error`` |
|
326 Raise an exception instead of printing a warning message. |
|
327 |
|
328 The full form of argument is:: |
|
329 |
|
330 action:message:category:module:line |
|
331 |
|
332 Here, *action* is as explained above but only applies to messages that match |
|
333 the remaining fields. Empty fields match all values; trailing empty fields |
|
334 may be omitted. The *message* field matches the start of the warning message |
|
335 printed; this match is case-insensitive. The *category* field matches the |
|
336 warning category. This must be a class name; the match test whether the |
|
337 actual warning category of the message is a subclass of the specified warning |
|
338 category. The full class name must be given. The *module* field matches the |
|
339 (fully-qualified) module name; this match is case-sensitive. The *line* |
|
340 field matches the line number, where zero matches all line numbers and is |
|
341 thus equivalent to an omitted line number. |
|
342 |
|
343 .. seealso:: |
|
344 :mod:`warnings` -- the warnings module |
|
345 |
|
346 :pep:`230` -- Warning framework |
|
347 |
|
348 |
|
349 .. cmdoption:: -x |
|
350 |
|
351 Skip the first line of the source, allowing use of non-Unix forms of |
|
352 ``#!cmd``. This is intended for a DOS specific hack only. |
|
353 |
|
354 .. warning:: The line numbers in error messages will be off by one! |
|
355 |
|
356 |
|
357 .. cmdoption:: -3 |
|
358 |
|
359 Warn about Python 3.x incompatibilities. Among these are: |
|
360 |
|
361 * :meth:`dict.has_key` |
|
362 * :func:`apply` |
|
363 * :func:`callable` |
|
364 * :func:`coerce` |
|
365 * :func:`execfile` |
|
366 * :func:`reduce` |
|
367 * :func:`reload` |
|
368 |
|
369 Using these will emit a :exc:`DeprecationWarning`. |
|
370 |
|
371 .. versionadded:: 2.6 |
|
372 |
|
373 |
|
374 |
|
375 .. _using-on-envvars: |
|
376 |
|
377 Environment variables |
|
378 --------------------- |
|
379 |
|
380 These environment variables influence Python's behavior. |
|
381 |
|
382 .. envvar:: PYTHONHOME |
|
383 |
|
384 Change the location of the standard Python libraries. By default, the |
|
385 libraries are searched in :file:`{prefix}/lib/python{version}` and |
|
386 :file:`{exec_prefix}/lib/python{version}`, where :file:`{prefix}` and |
|
387 :file:`{exec_prefix}` are installation-dependent directories, both defaulting |
|
388 to :file:`/usr/local`. |
|
389 |
|
390 When :envvar:`PYTHONHOME` is set to a single directory, its value replaces |
|
391 both :file:`{prefix}` and :file:`{exec_prefix}`. To specify different values |
|
392 for these, set :envvar:`PYTHONHOME` to :file:`{prefix}:{exec_prefix}`. |
|
393 |
|
394 |
|
395 .. envvar:: PYTHONPATH |
|
396 |
|
397 Augment the default search path for module files. The format is the same as |
|
398 the shell's :envvar:`PATH`: one or more directory pathnames separated by |
|
399 :data:`os.pathsep` (e.g. colons on Unix or semicolons on Windows). |
|
400 Non-existent directories are silently ignored. |
|
401 |
|
402 In addition to normal directories, individual :envvar:`PYTHONPATH` entries |
|
403 may refer to zipfiles containing pure Python modules (in either source or |
|
404 compiled form). Extension modules cannot be imported from zipfiles. |
|
405 |
|
406 The default search path is installation dependent, but generally begins with |
|
407 :file:`{prefix}/lib/python{version}`` (see :envvar:`PYTHONHOME` above). It |
|
408 is *always* appended to :envvar:`PYTHONPATH`. |
|
409 |
|
410 An additional directory will be inserted in the search path in front of |
|
411 :envvar:`PYTHONPATH` as described above under |
|
412 :ref:`using-on-interface-options`. The search path can be manipulated from |
|
413 within a Python program as the variable :data:`sys.path`. |
|
414 |
|
415 |
|
416 .. envvar:: PYTHONSTARTUP |
|
417 |
|
418 If this is the name of a readable file, the Python commands in that file are |
|
419 executed before the first prompt is displayed in interactive mode. The file |
|
420 is executed in the same namespace where interactive commands are executed so |
|
421 that objects defined or imported in it can be used without qualification in |
|
422 the interactive session. You can also change the prompts :data:`sys.ps1` and |
|
423 :data:`sys.ps2` in this file. |
|
424 |
|
425 |
|
426 .. envvar:: PYTHONY2K |
|
427 |
|
428 Set this to a non-empty string to cause the :mod:`time` module to require |
|
429 dates specified as strings to include 4-digit years, otherwise 2-digit years |
|
430 are converted based on rules described in the :mod:`time` module |
|
431 documentation. |
|
432 |
|
433 |
|
434 .. envvar:: PYTHONOPTIMIZE |
|
435 |
|
436 If this is set to a non-empty string it is equivalent to specifying the |
|
437 :option:`-O` option. If set to an integer, it is equivalent to specifying |
|
438 :option:`-O` multiple times. |
|
439 |
|
440 |
|
441 .. envvar:: PYTHONDEBUG |
|
442 |
|
443 If this is set to a non-empty string it is equivalent to specifying the |
|
444 :option:`-d` option. If set to an integer, it is equivalent to specifying |
|
445 :option:`-d` multiple times. |
|
446 |
|
447 |
|
448 .. envvar:: PYTHONINSPECT |
|
449 |
|
450 If this is set to a non-empty string it is equivalent to specifying the |
|
451 :option:`-i` option. |
|
452 |
|
453 This variable can also be modified by Python code using :data:`os.environ` |
|
454 to force inspect mode on program termination. |
|
455 |
|
456 |
|
457 .. envvar:: PYTHONUNBUFFERED |
|
458 |
|
459 If this is set to a non-empty string it is equivalent to specifying the |
|
460 :option:`-u` option. |
|
461 |
|
462 |
|
463 .. envvar:: PYTHONVERBOSE |
|
464 |
|
465 If this is set to a non-empty string it is equivalent to specifying the |
|
466 :option:`-v` option. If set to an integer, it is equivalent to specifying |
|
467 :option:`-v` multiple times. |
|
468 |
|
469 |
|
470 .. envvar:: PYTHONCASEOK |
|
471 |
|
472 If this is set, Python ignores case in :keyword:`import` statements. This |
|
473 only works on Windows. |
|
474 |
|
475 |
|
476 .. envvar:: PYTHONDONTWRITEBYTECODE |
|
477 |
|
478 If this is set, Python won't try to write ``.pyc`` or ``.pyo`` files on the |
|
479 import of source modules. |
|
480 |
|
481 .. versionadded:: 2.6 |
|
482 |
|
483 .. envvar:: PYTHONIOENCODING |
|
484 |
|
485 Overrides the encoding used for stdin/stdout/stderr, in the syntax |
|
486 ``encodingname:errorhandler``. The ``:errorhandler`` part is optional and |
|
487 has the same meaning as in :func:`str.encode`. |
|
488 |
|
489 .. versionadded:: 2.6 |
|
490 |
|
491 |
|
492 .. envvar:: PYTHONNOUSERSITE |
|
493 |
|
494 If this is set, Python won't add the user site directory to sys.path |
|
495 |
|
496 .. versionadded:: 2.6 |
|
497 |
|
498 .. seealso:: |
|
499 |
|
500 :pep:`370` -- Per user site-packages directory |
|
501 |
|
502 |
|
503 .. envvar:: PYTHONUSERBASE |
|
504 |
|
505 Sets the base directory for the user site directory |
|
506 |
|
507 .. versionadded:: 2.6 |
|
508 |
|
509 .. seealso:: |
|
510 |
|
511 :pep:`370` -- Per user site-packages directory |
|
512 |
|
513 |
|
514 .. envvar:: PYTHONEXECUTABLE |
|
515 |
|
516 If this environment variable is set, ``sys.argv[0]`` will be set to its |
|
517 value instead of the value got through the C runtime. Only works on |
|
518 Mac OS X. |
|
519 |
|
520 |
|
521 Debug-mode variables |
|
522 ~~~~~~~~~~~~~~~~~~~~ |
|
523 |
|
524 Setting these variables only has an effect in a debug build of Python, that is, |
|
525 if Python was configured with the :option:`--with-pydebug` build option. |
|
526 |
|
527 .. envvar:: PYTHONTHREADDEBUG |
|
528 |
|
529 If set, Python will print threading debug info. |
|
530 |
|
531 .. versionchanged:: 2.6 |
|
532 Previously, this variable was called ``THREADDEBUG``. |
|
533 |
|
534 .. envvar:: PYTHONDUMPREFS |
|
535 |
|
536 If set, Python will dump objects and reference counts still alive after |
|
537 shutting down the interpreter. |
|
538 |
|
539 |
|
540 .. envvar:: PYTHONMALLOCSTATS |
|
541 |
|
542 If set, Python will print memory allocation statistics every time a new |
|
543 object arena is created, and on shutdown. |
|
544 |