Содержание страницы

1. Командная строка и окружение¶Command line and environment

Интерпретатор CPython сканирует командную строку и окружение на предмет различных настроек.

Особенности реализации CPython: схемы командной строки других реализаций могут отличаться. Для получения дополнительных сведений см. Альтернативные реализации.

1.1. Командная строка¶Command line

При запуске Python можно указать любые из этих опций:

python [-bBdEhiIOPqRsSuvVWx?] [-c command | -m module-name | script | - ] [args]

Наиболее распространённый вариант использования – это простой запуск скрипта:

python myscript.py

1.1.1. Опции интерфейса¶Interface options

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

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

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

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

-c <command>¶

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

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

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

-m <module-name>¶

Находит модуль с помощью стандартного механизма импорта и выполняет его содержимое как модуль __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 # подробнее

Вызывает событие аудита 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. Кроме того, автодополнение по табуляции и редактирование истории автоматически включаются, если это доступно на вашей платформе (см. конфигурацию Readline).

См. также

Запуск интерпретатора

Изменено в версии 3.4: Автоматическое включение автодополнения по табуляции и редактирования истории.

1.1.2. Общие опции¶Generic options

-?¶
-h¶
--help¶: Выводит краткое описание всех опций командной строки и соответствующих переменных окружения и завершает работу.

--help-env¶: Выводит краткое описание переменных окружения, специфичных для Python, и завершает работу.

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

--help-xoptions¶: Выводит описание специфичных для реализации опций -X и завершает работу.

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

--help-all¶: Выводит полную информацию об использовании и завершает работу.

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

-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. Прочие опции¶Miscellaneous options

-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.12.

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

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

-R¶

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

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

Рандомизация хешей предназначена для защиты от отказа в обслуживании, вызванного специально подобранными входными данными, которые используют наихудшую производительность при создании словаря – сложность O(n²). Подробнее см. https://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 и связанные с ним 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  # Предупреждать один раз на место вызова
-Werror    # Преобразовывать в исключения
-Walways   # Предупреждать каждый раз
-Wall      # То же, что и -Walways
-Wmodule   # Предупреждать один раз на вызывающий модуль
-Wonce     # Предупреждать один раз на процесс Python
-Wignore   # Никогда не предупреждать

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

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

action:message:category:module:lineno

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

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

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

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

Поле module соответствует полному имени модуля (с путём); при этом регистр учитывается.

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

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

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

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

-x¶: Пропускает первую строку исходного файла, позволяя использовать не-юниксовые формы #!cmd. Это предназначено только для специфического хака 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.12.
-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.12.
-X frozen_modules определяет, игнорируются ли замороженные модули механизмом импорта. Значение on означает, что они импортируются, а off – что они игнорируются. По умолчанию on, если это установленный Python (обычный случай). Если он находится в разработке (запуск из дерева исходников), то по умолчанию off. Обратите внимание, что замороженные модули importlib_bootstrap и importlib_bootstrap_external всегда используются, даже если этот флаг установлен в off. См. также PYTHON_FROZEN_MODULES.

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

Добавлено в версии 3.12.
-X perf_jit включает поддержку профилировщика Linux perf с поддержкой DWARF. Если эта опция задана, профилировщик perf сможет сообщать о вызовах Python, используя информацию DWARF. Эта опция доступна только на некоторых платформах и ничего не делает, если не поддерживается текущей системой. Значение по умолчанию – «выкл». См. также 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 и Free-threaded CPython.

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

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

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

Изменено в версии 3.9: Удалена опция -X showalloccount.

Изменено в версии 3.10: Удалена опция -X oldparser.

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

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

Установка переменной окружения TERM в значение dumb отключит цвет.

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

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

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

1.1.5. Параметры, которые не стоит использовать¶Options you shouldn’t use

-J¶: Зарезервировано для Jython.

1.2. Переменные окружения¶Environment variables

Эти переменные окружения влияют на поведение Python, они обрабатываются до параметров командной строки, кроме -E или -I. Принято, что параметры командной строки переопределяют переменные окружения в случае конфликта.

PYTHONHOME¶

Изменяет расположение стандартных библиотек Python. По умолчанию библиотеки ищутся в prefix/lib/pythonversion и exec_prefix/lib/pythonversion, где prefix и exec_prefix – это каталоги, зависящие от установки; оба по умолчанию имеют значение /usr/local.

Когда PYTHONHOME установлен в один каталог, его значение заменяет оба prefix и exec_prefix. Чтобы указать для них разные значения, установите PYTHONHOME в prefix:exec_prefix.

PYTHONPATH¶

Дополняет путь поиска модулей по умолчанию. Формат такой же, как у PATH оболочки: один или несколько путей к каталогам, разделённых os.pathsep (например, двоеточиями в Unix или точкой с запятой в Windows). Несуществующие каталоги игнорируются без предупреждения.

В дополнение к обычным каталогам, отдельные записи PYTHONPATH могут ссылаться на zip-файлы, содержащие чистые модули Python (в исходной или скомпилированной форме). Модули расширений не могут быть импортированы из zip-файлов.

Путь поиска по умолчанию зависит от установки, но обычно начинается с prefix/lib/pythonversion (см. PYTHONHOME выше). Он всегда добавляется к PYTHONPATH.

Дополнительный каталог будет вставлен в путь поиска перед PYTHONPATH, как описано выше в разделе Параметры интерфейса. Путь поиска можно изменять из программы Python как переменную sys.path.

PYTHONSAFEPATH¶: Если эта переменная установлена в непустую строку, потенциально небезопасный путь не будет добавляться в начало sys.path: подробнее см. параметр -P.

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

PYTHONPLATLIBDIR¶: Если эта переменная установлена в непустую строку, она переопределяет значение sys.platlibdir.

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

PYTHONSTARTUP¶

Если это имя читаемого файла, команды Python из этого файла выполняются перед отображением первого приглашения в интерактивном режиме. Файл выполняется в том же пространстве имён, что и интерактивные команды, поэтому определённые или импортированные в нём объекты могут использоваться без уточнения в интерактивном сеансе. Также в этом файле можно изменить приглашения sys.ps1 и sys.ps2 и хук sys.__interactivehook__.

Вызывает событие аудита cpython.run_startup с именем файла в качестве аргумента при вызове во время запуска.

PYTHONOPTIMIZE¶: Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -O. Если установлено целое число, это эквивалентно указанию -O несколько раз.

PYTHONBREAKPOINT¶: Если эта переменная установлена, она задаёт вызываемый объект в нотации с точками. Модуль, содержащий вызываемый объект, будет импортирован, а затем вызываемый объект будет запущен реализацией по умолчанию sys.breakpointhook(), которая сама вызывается встроенной breakpoint(). Если не установлена или установлена в пустую строку, это эквивалентно значению "pdb.set_trace". Установка в строку "0" заставляет реализацию по умолчанию sys.breakpointhook() ничего не делать и немедленно вернуться.

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

PYTHONDEBUG¶

Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -d. Если установлено целое число, это эквивалентно указанию -d несколько раз.

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

PYTHONINSPECT¶

Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -i.

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

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

Изменено в версии 3.12.5: (также 3.11.10, 3.10.15, 3.9.20 и 3.8.20) Генерирует аудируемые события.

Изменено в версии 3.13: По возможности использует PyREPL, в этом случае тоже выполняется PYTHONSTARTUP. Генерирует аудируемые события.

PYTHONUNBUFFERED¶: Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -u.

PYTHONVERBOSE¶: Если эта переменная установлена в непустую строку, это эквивалентно указанию опции -v. Если установлено целое число, это эквивалентно указанию -v несколько раз.

PYTHONCASEOK¶: Если эта переменная установлена, Python игнорирует регистр в операторах import. Это работает только в Windows и macOS.

PYTHONDONTWRITEBYTECODE¶: Если эта переменная установлена в непустую строку, Python не будет пытаться записывать файлы .pyc при импорте исходных модулей. Это эквивалентно указанию опции -B.

PYTHONPYCACHEPREFIX¶: Если эта переменная установлена, Python будет записывать файлы .pyc в зеркальное дерево каталогов по указанному пути, вместо каталогов __pycache__ внутри исходного дерева. Это эквивалентно указанию опции -X pycache_prefix=PATH.

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

PYTHONHASHSEED¶

Если эта переменная не установлена или установлена в random, используется случайное значение для инициализации хешей объектов str и bytes.

Если PYTHONHASHSEED установлено в целое число, оно используется как фиксированное начальное значение для генерации hash() для типов, охваченных рандомизацией хешей.

Его цель – обеспечить воспроизводимое хеширование, например, для самотестирования самого интерпретатора, или чтобы позволить кластеру процессов Python обмениваться значениями хешей.

Целое число должно быть десятичным числом в диапазоне [0, 4294967295]. Указание значения 0 отключит рандомизацию хешей.

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

PYTHONINTMAXSTRDIGITS¶: Если эта переменная установлена в целое число, она используется для настройки глобального ограничения длины преобразования целого числа в строку.

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

PYTHONIOENCODING¶

Если эта переменная установлена до запуска интерпретатора, она переопределяет кодировку, используемую для stdin/stdout/stderr, в синтаксисе encodingname:errorhandler. Обе части encodingname и :errorhandler необязательны и имеют то же значение, что и в str.encode().

Для stderr часть :errorhandler игнорируется; обработчик всегда будет 'backslashreplace'.

Изменено в версии 3.4: Часть encodingname теперь необязательна.

Изменено в версии 3.6: В Windows кодировка, указанная этой переменной, игнорируется для интерактивных буферов консоли, если также не указана PYTHONLEGACYWINDOWSSTDIO. Файлы и каналы, перенаправленные через стандартные потоки, не затрагиваются.

PYTHONNOUSERSITE¶: Если эта переменная установлена, Python не будет добавлять user site-packages directory в sys.path.

См. также

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

PYTHONUSERBASE¶: Определяет user base directory, который используется для вычисления пути к user site-packages directory и путей установки для python -m pip install --user.

См. также

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

PYTHONEXECUTABLE¶: Если эта переменная окружения установлена, sys.argv[0] будет установлено в её значение вместо значения, полученного через C runtime. Работает только на macOS.

PYTHONWARNINGS¶

Это эквивалентно опции -W. Если установлено в строку, разделённую запятыми, это эквивалентно многократному указанию -W, при этом фильтры, находящиеся позже в списке, имеют приоритет над теми, что раньше.

PYTHONWARNINGS=default  # Предупреждать один раз на место вызова
PYTHONWARNINGS=error    # Преобразовывать в исключения
PYTHONWARNINGS=always   # Предупреждать каждый раз
PYTHONWARNINGS=all      # То же, что и PYTHONWARNINGS=always
PYTHONWARNINGS=module   # Предупреждать один раз на вызывающий модуль
PYTHONWARNINGS=once     # Предупреждать один раз на процесс Python
PYTHONWARNINGS=ignore   # Никогда не предупреждать

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

PYTHONFAULTHANDLER¶: Если эта переменная окружения установлена в непустую строку, при запуске вызывается faulthandler.enable(): устанавливается обработчик сигналов SIGSEGV, SIGFPE, SIGABRT, SIGBUS и SIGILL для вывода трассировки Python. Это эквивалентно параметру -X faulthandler.

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

PYTHONTRACEMALLOC¶: Если эта переменная окружения установлена в непустую строку, запускается трассировка выделений памяти Python с помощью модуля tracemalloc. Значение переменной – максимальное количество фреймов, сохраняемых в трассировке стека. Например, PYTHONTRACEMALLOC=1 сохраняет только самый последний фрейм. См. функцию tracemalloc.start() для получения дополнительной информации. Это эквивалентно установке параметра -X tracemalloc.

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

PYTHONPROFILEIMPORTTIME¶: Если эта переменная окружения установлена в непустую строку, Python будет показывать, сколько времени занимает каждый импорт. Это эквивалентно указанию опции -X importtime.

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

PYTHONASYNCIODEBUG¶: Если эта переменная окружения установлена в непустую строку, включает режим отладки модуля asyncio.

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

PYTHONMALLOC¶

Устанавливает аллокаторы памяти Python и/или добавляет отладочные хуки.

Устанавливает семейство аллокаторов памяти, используемых Python:

default: использовать аллокаторы памяти по умолчанию.
malloc: использовать функцию malloc() библиотеки C для всех областей (PYMEM_DOMAIN_RAW, PYMEM_DOMAIN_MEM, PYMEM_DOMAIN_OBJ).
pymalloc: использовать аллокатор pymalloc для областей PYMEM_DOMAIN_MEM и PYMEM_DOMAIN_OBJ, а функцию malloc() – для области PYMEM_DOMAIN_RAW.
mimalloc: использовать аллокатор mimalloc для областей PYMEM_DOMAIN_MEM и PYMEM_DOMAIN_OBJ, а функцию malloc() – для области PYMEM_DOMAIN_RAW.

Установка отладочных хуков:

debug: установить отладочные хуки поверх аллокаторов памяти по умолчанию.
malloc_debug: то же, что malloc, но также устанавливает отладочные хуки.
pymalloc_debug: то же, что pymalloc, но также устанавливает отладочные хуки.
mimalloc_debug: то же, что mimalloc, но также устанавливает отладочные хуки.

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

Изменено в версии 3.7: Добавлен аллокатор "default".

PYTHONMALLOCSTATS¶

Если установлена в непустую строку, Python будет выводить статистику аллокатора памяти pymalloc каждый раз, когда создаётся новая арена объекта pymalloc, а также при завершении работы.

Эта переменная игнорируется, если переменная окружения PYTHONMALLOC используется для принудительного выбора аллокатора malloc() из библиотеки C, или если Python скомпилирован без поддержки pymalloc.

Изменено в версии 3.6: Теперь эту переменную можно также использовать в Python, скомпилированном в режиме релиза. Теперь она не действует, если установлена в пустую строку.

PYTHONLEGACYWINDOWSFSENCODING¶

Если установлена в непустую строку, режим кодировки файловой системы и обработчика ошибок по умолчанию вернётся к значениям до версии 3.6: ‘mbcs’ и ‘replace’ соответственно. В противном случае используются новые значения по умолчанию: ‘utf-8’ и ‘surrogatepass’.

Это также можно включить во время выполнения с помощью sys._enablelegacywindowsfsencoding().

Доступность: Windows.

Добавлено в версии 3.6: Подробнее см. PEP 529.

PYTHONLEGACYWINDOWSSTDIO¶

Если задана непустая строка, не использует новые средства чтения и записи консоли. Это означает, что символы Unicode будут кодироваться в соответствии с активной кодовой страницей консоли, а не с помощью utf-8.

Эта переменная игнорируется, если стандартные потоки перенаправлены (в файлы или каналы), а не ссылаются на буферы консоли.

Доступность: Windows.

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

PYTHONCOERCECLOCALE¶

Если установлена в значение 0, заставляет главное приложение командной строки Python пропустить принудительное преобразование устаревших локалей C и POSIX на основе ASCII в более современную альтернативу на основе UTF-8.

Если эта переменная не установлена (или установлена в значение, отличное от 0), переменная окружения LC_ALL для переопределения локали также не установлена, и текущая локаль для категории LC_CTYPE сообщается как локаль по умолчанию C или явно основанная на ASCII локаль POSIX, то CLI Python попытается настроить следующие локали для категории LC_CTYPE в указанном порядке перед загрузкой среды выполнения интерпретатора:

C.UTF-8
C.utf8
UTF-8

Если установка одной из этих категорий локали проходит успешно, то переменная окружения LC_CTYPE также будет соответствующим образом установлена в окружении текущего процесса до инициализации среды выполнения Python. Это гарантирует, что помимо того, что обновленная настройка видна как самому интерпретатору, так и другим компонентам, учитывающим локаль, работающим в том же процессе (например, библиотеке GNU readline), она также будет видна в подпроцессах (независимо от того, выполняют ли эти процессы интерпретатор Python или нет), а также в операциях, которые запрашивают окружение, а не текущую локаль C (таких как собственная функция locale.getdefaultlocale() в Python).

Настройка одной из этих локалей (явно или через неявное принуждение локали) автоматически включает обработчик ошибок surrogateescape для sys.stdin и sys.stdout (sys.stderr продолжает использовать backslashreplace, как и в любой другой локали). Это поведение обработки потоков можно переопределить, используя PYTHONIOENCODING, как обычно.

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

Также обратите внимание, что даже если принуждение локали отключено или не удается найти подходящую целевую локаль, PYTHONUTF8 все равно будет активирован по умолчанию в устаревших локалях на основе ASCII. Обе функции должны быть отключены, чтобы заставить интерпретатор использовать ASCII вместо UTF-8 для системных интерфейсов.

Доступность: Unix.

Добавлено в версии 3.7: См. PEP 538 для получения дополнительной информации.

PYTHONDEVMODE¶: Если эта переменная окружения установлена в непустую строку, включает режим разработки Python, добавляя дополнительные проверки во время выполнения, которые слишком дороги для включения по умолчанию. Это эквивалентно установке опции -X dev.

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

PYTHONUTF8¶

Если установлено в 1, включает режим UTF-8 Python.

Если установлено в 0, отключает режим UTF-8 Python.

Установка любой другой непустой строки вызывает ошибку при инициализации интерпретатора.

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

PYTHONWARNDEFAULTENCODING¶

Если эта переменная окружения установлена в непустую строку, выдается EncodingWarning, когда используется кодировка по умолчанию, зависящая от локали.

Подробнее см. Opt-in EncodingWarning.

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

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

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

PYTHONPERFSUPPORT¶

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

Если установлено в 0, отключает поддержку профилировщика Linux perf.

См. также опцию командной строки -X perf и поддержку Python для профилировщика Linux perf.

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

PYTHON_PERF_JIT_SUPPORT¶

Если эта переменная установлена в ненулевое значение, она включает поддержку профилировщика Linux perf, чтобы он мог обнаруживать вызовы Python с использованием информации DWARF.

Если установлено в 0, отключает поддержку профилировщика Linux perf.

См. также опцию командной строки -X perf_jit и поддержку Python для профилировщика Linux perf.

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

PYTHON_CPU_COUNT¶

Если эта переменная установлена в положительное целое число, она переопределяет возвращаемые значения os.cpu_count() и os.process_cpu_count().

См. также опцию командной строки -X cpu_count.

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

PYTHON_FROZEN_MODULES¶

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

См. также опцию командной строки -X frozen_modules.

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

PYTHON_COLORS¶: Если этой переменной присвоено значение 1, интерпретатор будет раскрашивать различные виды вывода. Значение 0 отключает это поведение. См. также Управление цветом.

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

PYTHON_BASIC_REPL¶: Если эта переменная установлена в любое значение, интерпретатор не будет пытаться загрузить REPL на основе Python, который требует curses и readline, а вместо этого будет использовать традиционный REPL на основе синтаксического анализатора.

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

PYTHON_HISTORY¶: Эту переменную окружения можно использовать для указания расположения файла .python_history (по умолчанию он находится в .python_history в домашнем каталоге пользователя).

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

PYTHON_GIL¶

Если этой переменной присвоено значение 1, глобальная блокировка интерпретатора (GIL) будет принудительно включена. Значение 0 принудительно отключает GIL (требуется Python, собранный с опцией сборки --disable-gil).

См. также опцию командной строки -X gil, которая имеет приоритет над этой переменной, и Free-threaded CPython.

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

PYTHON_JIT¶: В сборках, где доступна экспериментальная JIT-компиляция, эта переменная может принудительно отключить (0) или включить (1) JIT при запуске интерпретатора.

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

1.2.1. Переменные режима отладки¶Debug-mode variables

PYTHONDUMPREFS¶

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

Требуется Python, собранный с опцией сборки --with-trace-refs.

PYTHONDUMPREFSFILE¶

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

Требуется Python, собранный с опцией сборки --with-trace-refs.

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

PYTHON_PRESITE¶

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

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

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

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

Требуется Python, собранный с опцией сборки --with-pydebug.

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