Командная строка и окружение

1.1.1. Параметры интерфейса

Интерфейс интерпретатора похож на интерфейс оболочки UNIX, но предоставляет несколько дополнительных способов вызова:

• При вызове со стандартным вводом, подключённым к tty-устройству, интерпретатор предлагает вводить команды и выполняет их, пока не прочитает EOF (символ конца файла; его можно ввести с помощью Ctrl-D в UNIX или Ctrl-Z, Enter в Windows). Подробнее об интерактивном режиме см. в разделе Интерактивный режим.
• При вызове с аргументом в виде имени файла или с файлом в качестве стандартного ввода интерпретатор считывает и выполняет скрипт из этого файла.
• При вызове с аргументом в виде имени каталога интерпретатор считывает и выполняет скрипт с соответствующим именем из этого каталога.
• При вызове с -c command интерпретатор выполняет инструкции Python, заданные в виде команды. Команда может содержать несколько инструкций, разделённых символами новой строки. Начальные пробелы в инструкциях Python имеют значение!
• При вызове с -m module-name указанный модуль находится в пути поиска модулей Python и выполняется как скрипт.

В неинтерактивном режиме весь ввод анализируется до начала выполнения.

Параметр интерфейса завершает список параметров, обрабатываемых интерпретатором; все последующие аргументы попадут в sys.argv — обратите внимание, что первый элемент, с индексом ноль (sys.argv[0]), представляет собой строку, содержащую исходный код программы.

-c <command>

Выполнить код Python в команде. Команда может содержать одну или несколько инструкций, разделённых символами новой строки; начальные пробелы, как и в обычном коде модуля, имеют значение.

Если задан этот параметр, первым элементом sys.argv будет "-c", а текущий каталог будет добавлен в начало sys.path (что позволяет импортировать модули из этого каталога как модули верхнего уровня).

Вызывает событие аудита cpython.run_command с аргументом command.

-m <module-name>

Выполнить поиск указанного модуля в sys.path и выполнить его содержимое как модуль __main__.

Поскольку аргументом является имя модуля, указывать расширение файла не нужно (.py). Имя модуля должно быть допустимым абсолютным именем модуля Python, однако реализация не всегда проверяет это (например, она может разрешать использовать имя, содержащее дефис).

Также разрешены имена пакетов (в том числе пакетов пространств имён). Если вместо обычного модуля указано имя пакета, интерпретатор выполнит <pkg>.__main__ как главный модуль. Такое поведение намеренно аналогично обработке каталогов и zip-файлов, переданных интерпретатору в качестве аргумента скрипта.

Примечание

Этот параметр нельзя использовать со встроенными модулями и модулями расширений, написанными на C, поскольку у них нет файлов модулей Python. Однако его можно использовать для предварительно скомпилированных модулей, даже если исходный файл недоступен.

Если задан этот параметр, первым элементом sys.argv будет полный путь к файлу модуля (пока файл модуля находится, первый элемент будет равен "-m"). Как и при использовании параметра -c, текущий каталог будет добавлен в начало sys.path.

Параметр -I можно использовать для запуска скрипта в изолированном режиме, при котором sys.path не содержит ни текущего каталога, ни каталога site-packages пользователя. Также игнорируются все переменные окружения PYTHON*.

Во многих модулях стандартной библиотеки содержится код, который выполняется при запуске модуля в качестве скрипта. Например, модуль timeit:

python -m timeit -s "setup here" "benchmarked code here"
python -m timeit -h # for details

Вызывает событие аудита cpython.run_module с аргументом module-name.

См. также

runpy.run_module()

Эквивалентные возможности, доступные непосредственно из кода Python

PEP 338 — Выполнение модулей в качестве скриптов

Изменено в версии 3.1: Укажите имя пакета, чтобы запустить подмодуль __main__.

Изменено в версии 3.4: Также поддерживаются пакеты пространств имён

-

Считывать команды со стандартного ввода (sys.stdin). Если стандартный ввод является терминалом, подразумевается параметр -i.

Если задан этот параметр, первым элементом sys.argv будет "-", а текущий каталог будет добавлен в начало sys.path.

Вызывает событие аудита cpython.run_stdin без аргументов.

<script>

Выполнить код Python, содержащийся в скрипте, который должен быть путём в файловой системе (абсолютным или относительным), указывающим на файл Python, каталог с файлом __main__.py или zip-файл с файлом __main__.py.

Если задан этот параметр, первым элементом sys.argv будет имя скрипта, указанное в командной строке.

Если имя скрипта непосредственно указывает на файл Python, каталог, содержащий этот файл, добавляется в начало sys.path, а файл выполняется как модуль __main__.

Если имя скрипта указывает на каталог или zip-файл, имя скрипта добавляется в начало sys.path, а файл __main__.py в этом расположении выполняется как модуль __main__.

Параметр -I можно использовать для запуска скрипта в изолированном режиме, при котором sys.path не содержит ни каталога скрипта, ни каталога site-packages пользователя. Также игнорируются все переменные окружения PYTHON*.

Вызывает событие аудита cpython.run_file с аргументом filename.

См. также

runpy.run_path()

Эквивалентные возможности, доступные непосредственно из кода Python

Если параметр интерфейса не указан, подразумевается -i, sys.argv[0] — пустая строка (""), а текущий каталог добавляется в начало sys.path. Кроме того, если это поддерживается платформой, автоматически включаются автодополнение по клавише Tab и редактирование истории (см. раздел Настройка Readline).

1.1.2. Общие параметры

-?

-h

--help

Вывести краткое описание всех параметров командной строки и соответствующих переменных окружения и завершить работу.

--help-env

Вывести краткое описание переменных окружения, относящихся к Python, и завершить работу.

Добавлено в версии 3.11.

--help-xoptions

Вывести описание зависящих от реализации параметров -X и завершить работу.

Добавлено в версии 3.11.

--help-all

Вывести полную информацию об использовании и завершить работу.

Добавлено в версии 3.11.

-V

--version

Вывести номер версии Python и завершить работу. Пример вывода:

Python 3.8.0b2+

Если указать параметр дважды, будет выведена дополнительная информация о сборке, например:

Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00)
[GCC 6.2.0 20161005]

Добавлено в версии 3.6: Параметр -VV.

1.1.3. Прочие параметры

-b

Выдавать предупреждение при преобразовании bytes или bytearray в str без указания кодировки, а также при сравнении bytes или bytearray с str или bytes с int. Выдавать ошибку, если параметр указан дважды (-bb).

Изменено в версии 3.5: Также влияет на сравнение bytes с int.

-B

Если этот параметр задан, Python не будет пытаться записывать файлы .pyc при импорте исходных модулей. См. также PYTHONDONTWRITEBYTECODE.

--check-hash-based-pycs default|always|never

Управлять проверкой файлов .pyc на основе хеша. См. Инвалидация кэшированного байт-кода. При значении default файлы кэша байт-кода на основе хеша, как проверяемые, так и непроверяемые, проверяются в соответствии с семантикой по умолчанию. При значении always все файлы .pyc на основе хеша, как проверяемые, так и непроверяемые, сверяются с соответствующим исходным файлом. При значении never файлы .pyc на основе хеша не сверяются с соответствующими исходными файлами.

Этот параметр не влияет на семантику файлов .pyc на основе временных меток.

-d

Включить вывод отладочной информации анализатора (только для экспертов). См. также переменную окружения PYTHONDEBUG.

Этот параметр требует отладочной сборки Python, иначе он игнорируется.

-E

Игнорировать все переменные окружения PYTHON*, например PYTHONPATH и PYTHONHOME, если они заданы.

См. также параметры -P и -I (изолированный режим).

-i

Перейти в интерактивный режим после выполнения.

Использование параметра -i приводит к переходу в интерактивный режим в следующих случаях:

• Если в качестве первого аргумента передан скрипт
• Если используется параметр -c
• Если используется параметр -m

Интерактивный режим запустится, даже если sys.stdin не является терминалом. Файл PYTHONSTARTUP не считывается.

Это может быть полезно для проверки глобальных переменных или трассировки стека, если скрипт вызывает исключение. См. также PYTHONINSPECT.

-I

Запустить Python в изолированном режиме. Это также подразумевает параметры -E, -P и -s.

В изолированном режиме sys.path не содержит ни каталог скрипта, ни каталог пользовательских site-packages. Все переменные окружения PYTHON* также игнорируются. Могут вводиться и другие ограничения, чтобы не допустить внедрения пользователем вредоносного кода.

Добавлено в версии 3.4.

-O

Удалить инструкции assert и любой код, зависящий от значения __debug__. Изменить имя скомпилированных файлов (байт-кода), добавив .opt-1 перед расширением .pyc (см. PEP 488). См. также PYTHONOPTIMIZE.

Изменено в версии 3.5: Изменять имена файлов .pyc согласно PEP 488.

-OO

Выполнить -O, а также удалить строки документации. Изменить имя скомпилированных файлов (байт-кода), добавив .opt-2 перед расширением .pyc (см. PEP 488).

Изменено в версии 3.5: Изменять имена файлов .pyc согласно PEP 488.

-P

Не добавлять потенциально небезопасный путь в начало sys.path:

• python -m module командная строка: не добавлять в начало текущий рабочий каталог.
• python script.py командная строка: не добавлять в начало каталог скрипта. Если это символическая ссылка, разрешить символические ссылки.
• python -c code и python (REPL) командные строки: не добавлять в начало пустую строку, которая обозначает текущий рабочий каталог.

См. также переменную окружения PYTHONSAFEPATH и параметры -E и -I (изолированный режим).

Добавлено в версии 3.11.

-q

Не выводить сообщения об авторских правах и версии, даже в интерактивном режиме.

Добавлено в версии 3.2.

-R

Включить рандомизацию хешей. Этот параметр действует, только если переменная окружения PYTHONHASHSEED задана значением, отличным от random, поскольку рандомизация хешей включена по умолчанию.

В предыдущих версиях Python этот параметр включает рандомизацию хешей, при которой значения __hash__() объектов str и bytes «солятся» непредсказуемым случайным значением. Хотя в рамках отдельного процесса Python они остаются неизменными, их значения непредсказуемы при повторных запусках Python.

Рандомизация хешей предназначена для защиты от отказа в обслуживании, вызванного специально подобранными входными данными, которые приводят к наихудшей производительности при создании dict со сложностью O(n²). Подробности см. на странице http://ocert.org/advisories/ocert-2011-003.html.

PYTHONHASHSEED позволяет задать фиксированное значение секрета начального значения хеша.

Добавлено в версии 3.2.3.

Изменено в версии 3.7: Параметр больше не игнорируется.

-s

Не добавлять user site-packages directory в sys.path.

См. также PYTHONNOUSERSITE.

См. также

PEP 370 – Каталог site-packages для отдельного пользователя

-S

Отключить импорт модуля site и выполняемые им манипуляции с sys.path, зависящие от конфигурации сайта. Также отключить эти манипуляции, если модуль site явно импортируется позднее (вызовите site.main(), если хотите запустить их).

-u

Принудительно отключить буферизацию потоков stdout и stderr. Этот параметр не влияет на поток stdin.

См. также PYTHONUNBUFFERED.

Изменено в версии 3.7: Текстовый слой потоков stdout и stderr теперь не буферизуется.

-v

Выводить сообщение при каждой инициализации модуля, указывая место (имя файла или встроенный модуль), откуда он загружен. Если параметр указан дважды (-vv), выводить сообщение о каждом файле, проверяемом при поиске модуля. Также выводить сведения об очистке модулей при завершении.

Изменено в версии 3.10: Модуль site сообщает о путях, зависящих от конфигурации сайта, и обрабатываемых файлах .pth.

См. также PYTHONVERBOSE.

-W arg

Управление предупреждениями. По умолчанию механизм предупреждений Python выводит сообщения о предупреждениях в sys.stderr.

Самые простые настройки безусловно применяют заданное действие ко всем предупреждениям, выдаваемым процессом (включая предупреждения, которые в противном случае игнорировались бы по умолчанию):

-Wdefault  # Warn once per call location
-Werror    # Convert to exceptions
-Walways   # Warn every time
-Wall      # Same as -Walways
-Wmodule   # Warn once per calling module
-Wonce     # Warn once per Python process
-Wignore   # Never warn

Названия действий можно сокращать по желанию; интерпретатор преобразует их в соответствующие полные названия. Например, -Wi — это то же самое, что -Wignore.

Полная форма аргумента:

action:message:category:module:lineno

Пустые поля соответствуют любым значениям; завершающие пустые поля можно опустить. Например, -W ignore::DeprecationWarning игнорирует все предупреждения DeprecationWarning.

Поле действие описано выше, но применяется только к предупреждениям, соответствующим остальным полям.

Поле сообщение должно совпадать со всем текстом предупреждения; при сравнении регистр не учитывается.

Поле категория соответствует категории предупреждения (например, DeprecationWarning). Это должно быть имя класса; проверяется, является ли фактическая категория предупреждения подклассом указанной категории.

Поле модуль соответствует имени модуля (полностью квалифицированному); при сравнении учитывается регистр.

Поле номер строки соответствует номеру строки; ноль соответствует всем номерам строк и потому равнозначен отсутствующему номеру строки.

Можно указать несколько параметров -W; если предупреждение соответствует более чем одному параметру, выполняется действие для последнего совпавшего параметра. Недопустимые параметры -W игнорируются (однако при выдаче первого предупреждения печатается сообщение о недопустимых параметрах).

Управлять предупреждениями также можно с помощью переменной окружения PYTHONWARNINGS и из программы Python с помощью модуля warnings. Например, функцию warnings.filterwarnings() можно использовать для применения регулярного выражения к тексту предупреждения.

Дополнительные сведения см. в разделах Фильтр предупреждений и Описание фильтров предупреждений.

-x

Пропустить первую строку исходного кода, что позволяет использовать формы #!cmd, не предназначенные для Unix. Предназначено только для специфического хака DOS.

-X

Зарезервирован для различных параметров, специфичных для реализации. В настоящее время CPython определяет следующие возможные значения:

• -X faulthandler для включения faulthandler. См. также PYTHONFAULTHANDLER.

  Добавлено в версии 3.3.

• -X showrefcount для вывода общего количества ссылок и числа используемых блоков памяти при завершении программы или после каждого оператора в интерактивном интерпретаторе. Работает только в отладочных сборках.

  Добавлено в версии 3.4.

• -X tracemalloc для начала отслеживания выделения памяти Python с помощью модуля tracemalloc. По умолчанию в трассировке сохраняется только самый последний кадр. Используйте -X tracemalloc=NFRAME, чтобы начать трассировку с ограничением в NFRAME кадров. Дополнительные сведения см. в tracemalloc.start() и PYTHONTRACEMALLOC.

  Добавлено в версии 3.4.

• -X int_max_str_digits настраивает ограничение длины преобразования целых чисел в строки. См. также PYTHONINTMAXSTRDIGITS.

  Добавлено в версии 3.11.

• -X importtime для отображения времени выполнения каждого импорта. Выводятся имя модуля, суммарное время (включая вложенные импорты) и собственное время (без учета вложенных импортов). Учтите, что в многопоточном приложении вывод может быть некорректным. Типичное использование: python3 -X importtime -c 'import asyncio'. См. также PYTHONPROFILEIMPORTTIME.

  Добавлено в версии 3.7.

• -X dev: включить режим разработки Python, добавляющий дополнительные проверки во время выполнения, слишком затратные для включения по умолчанию. См. также PYTHONDEVMODE.

  Добавлено в версии 3.7.

• -X utf8 включает режим UTF-8 Python. -X utf8=0 явно отключает режим UTF-8 Python (даже если он активировался бы автоматически). См. также PYTHONUTF8.

  Добавлено в версии 3.7.

• -X pycache_prefix=PATH включает запись файлов .pyc в параллельную иерархию каталогов, корнем которой является указанный каталог, вместо дерева кода. См. также PYTHONPYCACHEPREFIX.

  Добавлено в версии 3.8.

• -X warn_default_encoding выдает EncodingWarning, если при открытии файлов используется кодировка по умолчанию, заданная локалью. См. также PYTHONWARNDEFAULTENCODING.

  Добавлено в версии 3.10.

• -X no_debug_ranges отключает включение таблиц, сопоставляющих дополнительную информацию о расположении (конечную строку, начальное смещение столбца и конечное смещение столбца) каждой инструкции в объектах кода. Это полезно, когда нужны более компактные объекты кода и файлы pyc, а также позволяет скрыть дополнительные визуальные индикаторы расположения при отображении трассировок стека интерпретатором. См. также PYTHONNODEBUGRANGES.

  Добавлено в версии 3.11.

• -X frozen_modules определяет, будет ли механизм импорта игнорировать замороженные модули. Значение on означает, что они импортируются, а off — что они игнорируются. По умолчанию используется значение on, если это установленный Python (обычный случай). Если Python находится в разработке (запущен из дерева исходного кода), по умолчанию используется значение off. Обратите внимание, что замороженные модули importlib_bootstrap и importlib_bootstrap_external используются всегда, даже если для этого флага задано значение off. См. также PYTHON_FROZEN_MODULES.

  Добавлено в версии 3.11.

• -X perf включает поддержку профилировщика Linux perf. Если указан этот параметр, профилировщик perf сможет сообщать о вызовах Python. Этот параметр доступен только на некоторых платформах и ничего не делает, если текущая система его не поддерживает. Значение по умолчанию — «off». См. также PYTHONPERFSUPPORT и Поддержка Python в профилировщике Linux perf.

  Добавлено в версии 3.12.

• -X perf_jit включает поддержку профилировщика Linux perf с поддержкой DWARF. Если указан этот параметр, профилировщик perf сможет сообщать о вызовах Python, используя информацию DWARF. Этот параметр доступен только на некоторых платформах и ничего не делает, если текущая система его не поддерживает. Значение по умолчанию — «off». См. также PYTHON_PERF_JIT_SUPPORT и Поддержка Python в профилировщике Linux perf.

  Добавлено в версии 3.13.

• -X cpu_count=n переопределяет os.cpu_count(), os.process_cpu_count() и multiprocessing.cpu_count(). Значение n должно быть больше или равно 1. Этот параметр может быть полезен пользователям, которым необходимо ограничить ресурсы ЦП контейнерной системы. См. также PYTHON_CPU_COUNT. Если n равно default, переопределение не выполняется.

  Добавлено в версии 3.13.

• -X presite=package.module указывает модуль, который следует импортировать до выполнения модуля site и до создания модуля __main__. Поэтому импортированный модуль не является __main__. Это можно использовать для раннего выполнения кода во время инициализации Python. Для использования этого параметра Python необходимо собрать в режиме отладки. См. также PYTHON_PRESITE.

  Добавлено в версии 3.13.

• -X gil=0,1 принудительно отключает или включает GIL соответственно. Значение 0 доступно только в сборках, настроенных с параметром --disable-gil. См. также PYTHON_GIL и CPython без глобальной блокировки интерпретатора.

  Добавлено в версии 3.13.

Также этот параметр позволяет передавать произвольные значения и получать их через словарь sys._xoptions.

Добавлено в версии 3.2.

Изменено в версии 3.9: Параметр -X showalloccount удален.

Изменено в версии 3.10: Параметр -X oldparser удален.

1.1.4. Управление цветом

По умолчанию интерпретатор Python настроен на использование цветов для выделения вывода в определенных ситуациях, например при отображении трассировок стека. Это поведение можно контролировать с помощью различных переменных окружения.

Если задать переменной окружения TERM значение dumb, цвета будут отключены.

Если задана переменная окружения FORCE_COLOR, цвета будут включены независимо от значения TERM. Это полезно в системах CI, которые не являются терминалами, но могут отображать управляющие последовательности ANSI.

Если задана переменная окружения NO_COLOR, Python отключит все цвета в выводе. Эта настройка имеет приоритет над FORCE_COLOR.

Все эти переменные окружения используются и другими инструментами для управления цветом вывода. Чтобы управлять цветом только в интерпретаторе Python, можно использовать переменную окружения PYTHON_COLORS. Эта переменная имеет приоритет над NO_COLOR, которая, в свою очередь, имеет приоритет над FORCE_COLOR.

1.1.5. Параметры, которые не следует использовать

-J

Зарезервирован для использования в Jython.

1.2.1. Переменные режима отладки

PYTHONDUMPREFS

Если задана, Python после завершения работы интерпретатора выведет объекты и их счетчики ссылок, которые всё ещё существуют.

Для этого Python должен быть настроен с параметром сборки --with-trace-refs.

PYTHONDUMPREFSFILE

Если задана, Python запишет объекты и их счетчики ссылок, которые всё ещё существуют после завершения работы интерпретатора, в файл по пути, указанному значением этой переменной окружения.

Для этого Python должен быть настроен с параметром сборки --with-trace-refs.

Добавлено в версии 3.11.

PYTHON_PRESITE

Если для этой переменной задано имя модуля, этот модуль будет импортирован на раннем этапе жизненного цикла интерпретатора — до выполнения модуля site и до создания модуля __main__. Поэтому импортированный модуль не будет считаться модулем __main__.

Это можно использовать для выполнения кода на раннем этапе инициализации Python.

Чтобы импортировать подмодуль, укажите значение package.module, как в операторе импорта.

См. также параметр командной строки -X presite, который имеет приоритет над этой переменной.

Для этого Python должен быть настроен с параметром сборки --with-pydebug.

Добавлено в версии 3.13.