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

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

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

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

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

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

Самый распространенный вариант использования - это, конечно, простой вызов скрипта:

python myscript.py

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 (что позволит импортировать модули в этом каталоге как модули верхнего уровня).

Поднимает auditing event 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

Поднимает auditing event cpython.run_module с аргументом module-name.

См.также

runpy.run_module()

Эквивалентная функциональность напрямую доступна для кода Python

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

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

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

-

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

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

Поднимает auditing event cpython.run_stdin без аргументов.

<script>

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

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

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

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

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

Поднимает auditing event cpython.run_file с аргументом filename.

См.также

runpy.run_path()

Эквивалентная функциональность напрямую доступна для кода Python

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

См.также

Вызов переводчика

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

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

-?
-h
--help

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

--help-env

Выведите краткое описание переменных окружения, специфичных для Python, и выйдите из программы.

Added in version 3.11.

--help-xoptions

Выведите описание специфических для реализации -X опций и выйдите.

Added in version 3.11.

--help-all

Распечатайте полную информацию об использовании и выйдите.

Added in version 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]

Added in version 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.

Для этого параметра требуется значение debug build of 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* также игнорируются. Могут быть наложены дополнительные ограничения, чтобы предотвратить внедрение пользователем вредоносного кода.

Added in version 3.4.

-O

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

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

-OO

Делайте -O, а также отбрасывайте docstrings. Дополните имя файла для скомпилированных (bytecode) файлов, добавив .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 (изолированные).

Added in version 3.11.

-q

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

Added in version 3.2.

-R

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

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

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

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

Added in version 3.2.3.

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

-s

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

См. также PYTHONNOUSERSITE.

См.также

PEP 370 – Каталог пакетов сайта для каждого пользователя

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

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

Поле message должно соответствовать всему предупреждению; это соответствие не зависит от регистра.

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

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

Поле lineno соответствует номеру строки, где ноль соответствует всем номерам строк и, таким образом, эквивалентен опущенному номеру строки.

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

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

Более подробную информацию см. в разделах Фильтр предупреждений и Описание предупреждающих фильтров.

-x

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

-X

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

  • -X faulthandler, чтобы включить faulthandler. См. также PYTHONFAULTHANDLER.

    Added in version 3.3.

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

    Added in version 3.4.

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

    Added in version 3.4.

  • -X int_max_str_digits настраивает integer string conversion length limitation. См. также PYTHONINTMAXSTRDIGITS.

    Added in version 3.11.

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

    Added in version 3.7.

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

    Added in version 3.7.

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

    Added in version 3.7.

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

    Added in version 3.8.

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

    Added in version 3.10.

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

    Added in version 3.11.

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

    Added in version 3.11.

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

    Added in version 3.12.

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

    Added in version 3.13.

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

    Added in version 3.13.

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

    Added in version 3.13.

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

    Added in version 3.13.

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

Added in version 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. Переменные среды

Эти переменные окружения влияют на поведение 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.

Added in version 3.11.

PYTHONPLATLIBDIR

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

Added in version 3.9.

PYTHONSTARTUP

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

Поднимает auditing event cpython.run_startup с аргументом filename.

PYTHONOPTIMIZE

Если это значение задано непустой строкой, это эквивалентно указанию опции -O. Если задано целое число, это эквивалентно указанию -O несколько раз.

PYTHONBREAKPOINT

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

Added in version 3.7.

PYTHONDEBUG

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

Для этой переменной окружения требуется значение debug build of Python, иначе она игнорируется.

PYTHONINSPECT

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

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

PYTHONUNBUFFERED

Если это значение равно непустой строке, это эквивалентно указанию опции -u.

PYTHONVERBOSE

Если это значение задано непустой строкой, это эквивалентно указанию опции -v. Если задано целое число, это эквивалентно указанию -v несколько раз.

PYTHONCASEOK

Если это значение установлено, Python игнорирует регистр в операторах import. Это работает только в Windows и macOS.

PYTHONDONTWRITEBYTECODE

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

PYTHONPYCACHEPREFIX

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

Added in version 3.8.

PYTHONHASHSEED

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

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

Его цель - обеспечить повторяемость хэширования, например, для самотестирования самого интерпретатора или для того, чтобы кластер процессов python мог совместно использовать хэш-значения.

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

Added in version 3.2.3.

PYTHONINTMAXSTRDIGITS

Если эта переменная имеет целое значение, то она используется для настройки глобального integer string conversion length limitation интерпретатора.

Added in version 3.11.

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 – Каталог пакетов сайта для каждого пользователя

PYTHONUSERBASE

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

См.также

PEP 370 – Каталог пакетов сайта для каждого пользователя

PYTHONEXECUTABLE

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

PYTHONWARNINGS

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

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

PYTHONWARNINGS=default  # Warn once per call location
PYTHONWARNINGS=error    # Convert to exceptions
PYTHONWARNINGS=always   # Warn every time
PYTHONWARNINGS=module   # Warn once per calling module
PYTHONWARNINGS=once     # Warn once per Python process
PYTHONWARNINGS=ignore   # Never warn

Более подробную информацию см. в разделах Фильтр предупреждений и Описание предупреждающих фильтров.

PYTHONFAULTHANDLER

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

Added in version 3.3.

PYTHONTRACEMALLOC

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

Added in version 3.4.

PYTHONPROFILEIMPORTTIME

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

Added in version 3.7.

PYTHONASYNCIODEBUG

Если эта переменная окружения имеет значение непустой строки, включите debug mode модуля asyncio.

Added in version 3.4.

PYTHONMALLOC

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

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

Установите debug hooks:

  • debug: установите отладочные крючки поверх default memory allocators.

  • malloc_debug: то же самое, что и malloc, но с установкой отладочных крючков.

  • pymalloc_debug: то же самое, что и pymalloc, но с установкой отладочных крючков.

  • mimalloc_debug: то же самое, что и mimalloc, но с установкой отладочных крючков.

Added in version 3.6.

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

PYTHONMALLOCSTATS

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

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

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

PYTHONLEGACYWINDOWSFSENCODING

Если задана непустая строка, режим filesystem encoding and error handler по умолчанию возвращается к своим значениям до версии 3.6 - „mbcs“ и „replace“, соответственно. В противном случае будут использоваться новые значения по умолчанию „utf-8“ и „surrogatepass“.

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

Availability: Windows.

Added in version 3.6: Более подробную информацию см. в разделе PEP 529.

PYTHONLEGACYWINDOWSSTDIO

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

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

Availability: Windows.

Added in version 3.6.

PYTHONCOERCECLOCALE

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

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

  • C.UTF-8

  • C.utf8

  • UTF-8

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

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

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

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

Availability: Unix.

Added in version 3.7: Более подробную информацию см. в разделе PEP 538.

PYTHONDEVMODE

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

Added in version 3.7.

PYTHONUTF8

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

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

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

Added in version 3.7.

PYTHONWARNDEFAULTENCODING

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

Подробности см. в разделе ОптКодированиеПредупреждение.

Added in version 3.10.

PYTHONNODEBUGRANGES

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

Added in version 3.11.

PYTHONPERFSUPPORT

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

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

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

Added in version 3.12.

PYTHON_PERF_JIT_SUPPORT

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

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

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

Added in version 3.13.

PYTHON_CPU_COUNT

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

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

Added in version 3.13.

PYTHON_FROZEN_MODULES

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

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

Added in version 3.13.

PYTHON_COLORS

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

Added in version 3.13.

PYTHON_BASIC_REPL

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

Added in version 3.13.

PYTHON_HISTORY

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

Added in version 3.13.

PYTHON_GIL

Если эта переменная установлена в 1, будет принудительно включена глобальная блокировка интерпретатора (GIL). При установке значения 0 GIL будет отключена.

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

Требуется Python, сконфигурированный с опцией сборки --disable-gil.

Added in version 3.13.

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

PYTHONDUMPREFS

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

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

PYTHONDUMPREFSFILE

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

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

Added in version 3.11.

PYTHON_PRESITE

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

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

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

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

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

Added in version 3.13.