Lines Matching +full:before +full:- +full:script
6 .. _using-on-general:
14 .. impl-detail::
20 .. _using-on-cmdline:
23 ------------
27 python [-bBdEhiIOqsSuvVWx?] [-c command | -m module-name | script | - ] [args]
29 The most common use case is, of course, a simple invocation of a script::
34 .. _using-on-interface-options:
43 commands and executes them until an EOF (an end-of-file character, you can
44 produce that with :kbd:`Ctrl-D` on UNIX or :kbd:`Ctrl-Z, Enter` on Windows) is read.
46 reads and executes a script from that file.
48 appropriately named script from that directory.
49 * When called with ``-c command``, it executes the Python statement(s) given as
52 * When called with ``-m module-name``, the given module is located on the
53 Python module path and executed as a script.
55 In non-interactive mode, the entire input is parsed before it is executed.
58 all consecutive arguments will end up in :data:`sys.argv` -- note that the first
62 .. cmdoption:: -c <command>
69 ``"-c"`` and the current directory will be added to the start of
73 .. audit-event:: cpython.run_command command cmdoption-c
75 .. cmdoption:: -m <module-name>
90 script argument.
94 This option cannot be used with built-in modules and extension modules
101 first element will be set to ``"-m"``). As with the :option:`-c` option,
104 :option:`-I` option can be used to run the script in isolated mode where
106 site-packages directory. All :envvar:`PYTHON*` environment variables are
110 as a script. An example is the :mod:`timeit` module::
112 python -m timeit -s 'setup here' 'benchmarked code here'
113 python -m timeit -h # for details
115 .. audit-event:: cpython.run_module module-name cmdoption-m
121 :pep:`338` -- Executing modules as scripts
129 .. _cmdarg-dash:
131 .. describe:: -
134 a terminal, :option:`-i` is implied.
137 ``"-"`` and the current directory will be added to the start of
140 .. audit-event:: cpython.run_stdin "" ""
142 .. _cmdarg-script:
144 .. describe:: <script>
146 Execute the Python code contained in *script*, which must be a filesystem
152 script name as given on the command line.
154 If the script name refers directly to a Python file, the directory
158 If the script name refers to a directory or zipfile, the script name is
162 :option:`-I` option can be used to run the script in isolated mode where
163 :data:`sys.path` contains neither the script's directory nor the user's
164 site-packages directory. All :envvar:`PYTHON*` environment variables are
167 .. audit-event:: cpython.run_file filename
174 If no interface option is given, :option:`-i` is implied, ``sys.argv[0]`` is
176 start of :data:`sys.path`. Also, tab-completion and history editing is
178 :ref:`rlcompleter-config`).
180 .. seealso:: :ref:`tut-invoking`
183 Automatic enabling of tab-completion and history editing.
186 .. _using-on-generic-options:
191 .. cmdoption:: -?
192 -h
193 --help
198 .. cmdoption:: --help-env
200 Print a short description of Python-specific environment variables
205 .. cmdoption:: --help-xoptions
207 Print a description of implementation-specific :option:`-X` options
212 .. cmdoption:: --help-all
218 .. cmdoption:: -V
219 --version
223 .. code-block:: none
229 .. code-block:: none
235 The ``-VV`` option.
238 .. _using-on-misc-options:
243 .. cmdoption:: -b
247 option is given twice (:option:`!-bb`).
252 .. cmdoption:: -B
258 .. cmdoption:: --check-hash-based-pycs default|always|never
260 Control the validation behavior of hash-based ``.pyc`` files. See
261 :ref:`pyc-invalidation`. When set to ``default``, checked and unchecked
262 hash-based bytecode cache files are validated according to their default
263 semantics. When set to ``always``, all hash-based ``.pyc`` files, whether
265 file. When set to ``never``, hash-based ``.pyc`` files are not validated
268 The semantics of timestamp-based ``.pyc`` files are unaffected by this
272 .. cmdoption:: -d
278 .. cmdoption:: -E
283 See also the :option:`-P` and :option:`-I` (isolated) options.
286 .. cmdoption:: -i
288 When a script is passed as first argument or the :option:`-c` option is used,
289 enter interactive mode after executing the script or the command, even when
293 This can be useful to inspect global variables or a stack trace when a script
297 .. cmdoption:: -I
299 Run Python in isolated mode. This also implies :option:`-E`, :option:`-P`
300 and :option:`-s` options.
302 In isolated mode :data:`sys.path` contains neither the script's directory nor
303 the user's site-packages directory. All :envvar:`PYTHON*` environment
310 .. cmdoption:: -O
314 (:term:`bytecode`) files by adding ``.opt-1`` before the ``.pyc``
321 .. cmdoption:: -OO
323 Do :option:`-O` and also discard docstrings. Augment the filename
324 for compiled (:term:`bytecode`) files by adding ``.opt-2`` before the
331 .. cmdoption:: -P
335 * ``python -m module`` command line: Don't prepend the current working
337 * ``python script.py`` command line: Don't prepend the script's directory.
339 * ``python -c code`` and ``python`` (REPL) command lines: Don't prepend an
342 See also the :envvar:`PYTHONSAFEPATH` environment variable, and :option:`-E`
343 and :option:`-I` (isolated) options.
348 .. cmdoption:: -q
355 .. cmdoption:: -R
368 denial-of-service caused by carefully chosen inputs that exploit the worst
370 http://ocert.org/advisories/ocert-2011-003.html for details.
381 .. cmdoption:: -s
383 Don't add the :data:`user site-packages directory <site.USER_SITE>` to
388 :pep:`370` -- Per user site-packages directory
391 .. cmdoption:: -S
393 Disable the import of the module :mod:`site` and the site-dependent
399 .. cmdoption:: -u
410 .. cmdoption:: -v
413 (filename or built-in module) from which it is loaded. When given twice
414 (:option:`!-vv`), print a message for each file that is checked for when
418 The :mod:`site` module reports the site-specific paths
424 .. _using-on-warnings:
425 .. cmdoption:: -W arg
434 -Wdefault # Warn once per call location
435 -Werror # Convert to exceptions
436 -Walways # Warn every time
437 -Wmodule # Warn once per calling module
438 -Wonce # Warn once per Python process
439 -Wignore # Never warn
442 resolve them to the appropriate action name. For example, ``-Wi`` is the
443 same as ``-Wignore``.
450 example ``-W ignore::DeprecationWarning`` ignores all DeprecationWarning
457 case-insensitive.
465 case-sensitive.
470 Multiple :option:`-W` options can be given; when a warning matches more than
472 :option:`-W` options are ignored (though, a warning message is printed about
480 See :ref:`warning-filter` and :ref:`describing-warning-filters` for more
484 .. cmdoption:: -x
486 Skip the first line of the source, allowing use of non-Unix forms of
490 .. cmdoption:: -X
492 Reserved for various implementation-specific options. CPython currently
495 * ``-X faulthandler`` to enable :mod:`faulthandler`.
497 * ``-X showrefcount`` to output the total reference count and number of used
500 <debug-build>`.
501 * ``-X tracemalloc`` to start tracing Python memory allocations using the
503 stored in a traceback of a trace. Use ``-X tracemalloc=NFRAME`` to start
507 * ``-X int_max_str_digits`` configures the :ref:`integer string conversion
510 * ``-X importtime`` to show how long each import takes. It shows module
512 nested imports). Note that its output may be broken in multi-threaded
513 application. Typical usage is ``python3 -X importtime -c 'import
515 * ``-X dev``: enable :ref:`Python Development Mode <devmode>`, introducing
518 * ``-X utf8`` enables the :ref:`Python UTF-8 Mode <utf8-mode>`.
519 ``-X utf8=0`` explicitly disables :ref:`Python UTF-8 Mode <utf8-mode>`
522 * ``-X pycache_prefix=PATH`` enables writing ``.pyc`` files to a parallel
525 * ``-X warn_default_encoding`` issues a :class:`EncodingWarning` when the
526 locale-specific default encoding is used for opening files.
528 * ``-X no_debug_ranges`` disables the inclusion of the tables mapping extra
534 * ``-X frozen_modules`` determines whether or not frozen modules are
546 The :option:`-X` option was added.
549 The ``-X faulthandler`` option.
552 The ``-X showrefcount`` and ``-X tracemalloc`` options.
555 The ``-X showalloccount`` option.
558 The ``-X importtime``, ``-X dev`` and ``-X utf8`` options.
561 The ``-X pycache_prefix`` option. The ``-X dev`` option now logs
565 Using ``-X dev`` option, check *encoding* and *errors* arguments on
568 The ``-X showalloccount`` option has been removed.
571 The ``-X warn_default_encoding`` option.
573 .. deprecated-removed:: 3.9 3.10
574 The ``-X oldparser`` option.
577 The ``-X no_debug_ranges`` option.
580 The ``-X frozen_modules`` option.
583 The ``-X int_max_str_digits`` option.
589 .. cmdoption:: -J
596 .. _using-on-envvars:
599 ---------------------
602 before the command-line switches other than -E or -I. It is customary that
603 command-line switches override environmental variables where there is a
611 :file:`{exec_prefix}` are installation-dependent directories, both defaulting
624 Non-existent directories are silently ignored.
636 :ref:`using-on-interface-options`. The search path can be manipulated from
642 If this is set to a non-empty string, don't prepend a potentially unsafe
643 path to :data:`sys.path`: see the :option:`-P` option for details.
650 If this is set to a non-empty string, it overrides the :data:`sys.platlibdir`
659 executed before the first prompt is displayed in interactive mode. The file
665 .. audit-event:: cpython.run_startup filename envvar-PYTHONSTARTUP
673 If this is set to a non-empty string it is equivalent to specifying the
674 :option:`-O` option. If set to an integer, it is equivalent to specifying
675 :option:`-O` multiple times.
680 If this is set, it names a callable using dotted-path notation. The module
683 called by built-in :func:`breakpoint`. If not set, or set to the empty
692 If this is set to a non-empty string it is equivalent to specifying the
693 :option:`-d` option. If set to an integer, it is equivalent to specifying
694 :option:`-d` multiple times.
699 If this is set to a non-empty string it is equivalent to specifying the
700 :option:`-i` option.
708 If this is set to a non-empty string it is equivalent to specifying the
709 :option:`-u` option.
714 If this is set to a non-empty string it is equivalent to specifying the
715 :option:`-v` option. If set to an integer, it is equivalent to specifying
716 :option:`-v` multiple times.
727 If this is set to a non-empty string, Python won't try to write ``.pyc``
729 specifying the :option:`-B` option.
736 tree. This is equivalent to specifying the :option:`-X`
770 If this is set before running the interpreter, it overrides the encoding used
788 If this is set, Python won't add the :data:`user site-packages directory
793 :pep:`370` -- Per user site-packages directory
799 compute the path of the :data:`user site-packages directory <site.USER_SITE>`
800 and :ref:`Distutils installation paths <inst-alt-install-user>` for
801 ``python setup.py install --user``.
805 :pep:`370` -- Per user site-packages directory
816 This is equivalent to the :option:`-W` option. If set to a comma
817 separated string, it is equivalent to specifying :option:`-W` multiple
832 See :ref:`warning-filter` and :ref:`describing-warning-filters` for more
838 If this environment variable is set to a non-empty string,
842 :option:`-X` ``faulthandler`` option.
849 If this environment variable is set to a non-empty string, start tracing
855 This is equivalent to setting the :option:`-X` ``tracemalloc`` option.
862 If this environment variable is set to a non-empty string, Python will
864 This is equivalent to setting the :option:`-X` ``importtime`` option.
871 If this environment variable is set to a non-empty string, enable the
872 :ref:`debug mode <asyncio-debug-mode>` of the :mod:`asyncio` module.
884 <default-memory-allocators>`.
892 Install :ref:`debug hooks <pymem-debug-hooks>`:
895 allocators <default-memory-allocators>`.
907 If set to a non-empty string, Python will print statistics of the
922 If set to a non-empty string, the default :term:`filesystem encoding and
923 error handler` mode will revert to their pre-3.6 values of 'mbcs' and
924 'replace', respectively. Otherwise, the new defaults 'utf-8' and
937 If set to a non-empty string, does not use the new console reader and
939 the active console code page, rather than using utf-8.
952 to skip coercing the legacy ASCII-based C and POSIX locales to a more
953 capable UTF-8 based alternative.
958 ``C`` locale, or else the explicitly ASCII-based ``POSIX`` locale, then the
960 ``LC_CTYPE`` category in the order listed before loading the interpreter
963 * ``C.UTF-8``
965 * ``UTF-8``
969 environment before the Python runtime is initialized. This ensures that in
970 addition to being seen by both the interpreter itself and other locale-aware
979 :ref:`error handler <error-handlers>` for :data:`sys.stdin` and
991 default in legacy ASCII-based locales. Both features must be disabled in
992 order to force the interpreter to use ``ASCII`` instead of ``UTF-8`` for
1003 If this environment variable is set to a non-empty string, enable
1006 This is equivalent to setting the :option:`-X` ``dev`` option.
1012 If set to ``1``, enable the :ref:`Python UTF-8 Mode <utf8-mode>`.
1014 If set to ``0``, disable the :ref:`Python UTF-8 Mode <utf8-mode>`.
1016 Setting any other non-empty string causes an error during interpreter
1023 If this environment variable is set to a non-empty string, issue a
1024 :class:`EncodingWarning` when the locale-specific default encoding is used.
1026 See :ref:`io-encoding-warning` for details.
1042 Debug-mode variables
1049 Need a :ref:`debug build of Python <debug-build>`.
1051 .. deprecated-removed:: 3.10 3.12
1059 Need Python configured with the :option:`--with-trace-refs` build option.
1066 Need Python configured with the :option:`--with-trace-refs` build option.