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

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

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

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

При запуске Python можно указать любой из следующих параметров:

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

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

python myscript.py

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

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

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

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

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

-c <command>

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

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

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

Изменено в версии 3.14: Перед выполнением из команды автоматически удаляются отступы.

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

См. также

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

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

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²). Подробности см. на странице 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 и выполняемые им зависящие от сайта изменения 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.

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

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

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

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

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

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

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

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

-x

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

Это можно использовать, чтобы превратить сценарий Python в пакетный файл Windows. Как и при добавлении строки shebang и установке бита исполнения в Unix, расширение сценария Python можно изменить на .bat, а в начало сценария добавить следующую строку:

@py -x "%~f0" %* & exit /b

Или явно указать путь к интерпретатору Python:

@"C:\Path\to\python.exe" -x "%~f0" %* & exit /b

В отличие от строки shebang, которая является комментарием Python, эта строка не является допустимым синтаксисом Python, поэтому для её пропуска необходим параметр -x.

-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 для отображения времени выполнения каждого импорта. Выводятся имя модуля, суммарное время (включая вложенные импорты) и собственное время (без учёта вложенных импортов). Обратите внимание, что в многопоточном приложении вывод может быть некорректным. Типичное использование: python -X importtime -c 'import asyncio'.

-X importtime=2 включает дополнительный вывод, показывающий, что импортируемый модуль уже загружен. В таких случаях в обоих столбцах времени будет выведена строка cached.

См. также PYTHONPROFILEIMPORTTIME.

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

Изменено в версии 3.14: Добавлен -X importtime=2, позволяющий также отслеживать импорты уже загруженных модулей; значения, отличные от 1 и 2, зарезервированы для будущего использования.
-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 и Поддержка профилировщика Linux perf в Python.

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

Добавлено в версии 3.13.
-X disable_remote_debug отключает поддержку удалённой отладки, описанную в PEP 768. Это включает как возможность запланировать выполнение кода в другом процессе, так и возможность получать код для выполнения в текущем процессе.

Этот параметр доступен только на некоторых платформах и ничего не делает, если текущая система его не поддерживает. См. также PYTHON_DISABLE_REMOTE_DEBUG и PEP 768.

Добавлено в версии 3.14.
-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.
-X thread_inherit_context=0,1 приводит к тому, что Thread по умолчанию использует при запуске копию контекста вызывающего Thread.start(). В противном случае потоки запускаются с пустым контекстом. Если значение не задано, по умолчанию для этого параметра используется 1 в сборках без привязки к потокам и 0 в остальных случаях. См. также PYTHON_THREAD_INHERIT_CONTEXT.

Добавлено в версии 3.14.
-X context_aware_warnings=0,1 заставляет менеджер контекста warnings.catch_warnings использовать ContextVar для хранения состояния фильтра предупреждений. Если значение не задано, по умолчанию для этого параметра используется 1 в сборках без привязки к потокам и 0 в остальных случаях. См. также PYTHON_CONTEXT_AWARE_WARNINGS.

Добавлено в версии 3.14.
-X tlbc=0,1 включает (1, значение по умолчанию) или отключает (0) байт-код, локальный для потока, в сборках, настроенных с помощью --disable-gil. При отключении также отключается специализирующий интерпретатор. См. также PYTHON_TLBC.

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

Кроме того, он позволяет передавать произвольные значения и получать их через словарь sys._xoptions.

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

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

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

Удалено в версии 3.14: -J больше не зарезервирован для использования Jython и теперь не имеет специального значения.

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

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

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

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

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

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

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.

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

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.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 — Каталог site-packages для каждого пользователя

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

См. также

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

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=all      # Same as PYTHONWARNINGS=always
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.

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

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

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

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

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

Изменено в версии 3.14: Добавлено PYTHONPROFILEIMPORTTIME=2 для отслеживания импорта уже загруженных модулей.

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, а для домена PYMEM_DOMAIN_RAW — функцию malloc().
mimalloc: использовать распределитель mimalloc для доменов PYMEM_DOMAIN_MEM и PYMEM_DOMAIN_OBJ, а для домена PYMEM_DOMAIN_RAW — функцию malloc().

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

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

Примечание

В сборке со свободной многопоточностью значения malloc, malloc_debug, pymalloc и pymalloc_debug не поддерживаются. Допускаются только default, debug, mimalloc и mimalloc_debug.

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

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

PYTHONMALLOCSTATS

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

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

Изменено в версии 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 по умолчанию, либо явно заданной локалью POSIX на основе ASCII, то интерфейс командной строки Python попытается настроить для категории LC_CTYPE следующие локали в указанном порядке до загрузки среды выполнения интерпретатора:

C.UTF-8
C.utf8
UTF-8

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

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

Подробности см. в разделе Включение предупреждения EncodingWarning.

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

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

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

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_DISABLE_REMOTE_DEBUG

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

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

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

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: Если для этой переменной задано любое значение, интерпретатор не будет пытаться загрузить Python-реализацию REPL, которой требуется readline, а вместо неё будет использовать традиционную REPL на основе анализатора.

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

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

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

PYTHON_GIL

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

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

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

PYTHON_THREAD_INHERIT_CONTEXT: Если для этой переменной задано значение 1, при запуске Thread по умолчанию будет использовать копию контекста вызывающего Thread.start(). В противном случае новые потоки будут запускаться с пустым контекстом. Если переменная не задана, по умолчанию используется значение 1 для сборок без GIL и 0 — в остальных случаях. См. также -X thread_inherit_context.

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

PYTHON_CONTEXT_AWARE_WARNINGS: Если задано значение 1, менеджер контекста warnings.catch_warnings будет использовать ContextVar для хранения состояния фильтра предупреждений. Если переменная не задана, по умолчанию используется значение 1 для сборок без GIL и 0 — в остальных случаях. См. -X context_aware_warnings.

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

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

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

PYTHON_TLBC

Значение 1 включает байткод, локальный для потока. Значение 0 отключает байткод, локальный для потока, и специализирующийся интерпретатор. Применяется только к сборкам, настроенным с помощью --disable-gil.

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

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

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.