`cmdline.md`

499 строк · 32.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/using/cmdline.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 1. Командная строка и окружение89Интерпретатор CPython сканирует командную строку и окружение на предмет различных настроек.1011**Особенности реализации CPython:** схемы командной строки других реализаций могут отличаться. Для получения дополнительных сведений см. [*Альтернативные реализации*](https://python-all.ru/3.1/reference/introduction.html#implementations).1213## 1.1. Командная строка1415При запуске Python можно указать любые из этих опций:1617```text18python [-bBdEhiORsSuvVWx?] [-c command | -m module-name | script | - ] [args]19```2021Наиболее распространённый вариант использования – это простой запуск скрипта:2223```text24python myscript.py25```2627### 1.1.1. Параметры интерфейса2829Интерфейс интерпретатора напоминает интерфейс командной оболочки UNIX, но предоставляет дополнительные способы запуска:3031- При вызове с стандартным вводом, подключённым к tty-устройству, он выводит приглашение для команд и выполняет их, пока не будет прочитан EOF (символ конца файла; на UNIX его можно ввести с помощью *Ctrl-D*, а на Windows – *Ctrl-Z, Enter*).32- При вызове с именем файла в качестве аргумента или с файлом в качестве стандартного ввода он читает и выполняет скрипт из этого файла.33- При вызове с именем каталога в качестве аргумента он читает и выполняет соответствующий скрипт из этого каталога.34- При вызове с `-c command` интерпретатор выполняет инструкции Python, указанные в *command*. Эта *command* может содержать несколько инструкций, разделённых символами новой строки. Начальные пробелы в инструкциях Python имеют значение!35- При вызове с `-m module-name` интерпретатор находит указанный модуль по пути Python и выполняет его как скрипт.3637В неинтерактивном режиме весь ввод анализируется до его выполнения.3839Опция интерфейса завершает список опций, обрабатываемых интерпретатором; все последующие аргументы попадают в [`sys.argv`](https://python-all.ru/3.1/library/sys.html#sys.argv) – обратите внимание, что первый элемент с индексом ноль (`sys.argv[0]`) – это строка, отражающая источник программы.4041#### `-c <command>`4243Выполняет код Python, указанный в *command*. *command* может содержать одну или несколько инструкций, разделённых переводами строк; начальные пробелы, как и в обычном коде модуля, имеют значение.4445Если указана эта опция, первым элементом [`sys.argv`](https://python-all.ru/3.1/library/sys.html#sys.argv) будет `"-c"`, а текущий каталог будет добавлен в начало [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path) (что позволит импортировать модули из этого каталога как модули верхнего уровня).4647#### `-m <module-name>`4849Ищет указанный модуль в [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path) и выполняет его содержимое как модуль [`__main__`](https://python-all.ru/3.1/library/__main__.html#module-__main__).5051Поскольку аргументом является имя *модуля*, не следует указывать расширение файла (`.py`). Имя `module-name` должно быть допустимым именем модуля Python, хотя реализация может не всегда это контролировать (например, может позволить использовать имя, содержащее дефис).5253Имена пакетов также допускаются. Если вместо обычного модуля указано имя пакета, интерпретатор выполнит `<pkg>.__main__` в качестве главного модуля. Такое поведение намеренно сделано похожим на обработку каталогов и zip-файлов, которые передаются интерпретатору в качестве аргумента сценария.5455> **Примечание**56>57> Эту опцию нельзя использовать со встроенными модулями и модулями расширения, написанными на C, поскольку у них нет файлов модулей Python. Однако её можно использовать для предварительно скомпилированных модулей, даже если исходный файл недоступен.5859Если указана эта опция, первым элементом [`sys.argv`](https://python-all.ru/3.1/library/sys.html#sys.argv) будет полный путь к файлу модуля. Как и в случае с опцией [*-c*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-c), текущий каталог будет добавлен в начало [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path).6061Многие модули стандартной библиотеки содержат код, который вызывается при их выполнении как скрипта. Примером может служить модуль [`timeit`](https://python-all.ru/3.1/library/timeit.html#module-timeit):6263```text64python -mtimeit -s 'setup here' 'benchmarked code here'65python -mtimeit -h # for details66```6768> **См. также**69>70> [`runpy.run_module()`](https://python-all.ru/3.1/library/runpy.html#runpy.run_module) Эквивалентная функциональность, напрямую доступная из кода Python71>72> [**PEP 338**](https://python-all.ru/3.1/using/cmdline.html) – Выполнение модулей как сценариев7374Изменено в версии 3.1: Укажите имя пакета для запуска подмодуля `__main__`.7576#### `-`7778Читает команды из стандартного ввода ([`sys.stdin`](https://python-all.ru/3.1/library/sys.html#sys.stdin)). Если стандартный ввод – терминал, подразумевается опция [*-i*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-i).7980Если указана эта опция, первым элементом [`sys.argv`](https://python-all.ru/3.1/library/sys.html#sys.argv) будет `"-"`, а текущий каталог будет добавлен в начало [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path).8182#### `<script>`8384Выполняет код Python, содержащийся в *script*, который должен быть путём в файловой системе (абсолютным или относительным) и ссылаться на файл Python, каталог с файлом `__main__.py` или zip-файл с файлом `__main__.py`.8586Если указана эта опция, первым элементом [`sys.argv`](https://python-all.ru/3.1/library/sys.html#sys.argv) будет имя скрипта, указанное в командной строке.8788Если имя скрипта напрямую ссылается на файл Python, каталог, содержащий этот файл, добавляется в начало [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path), и файл выполняется как модуль [`__main__`](https://python-all.ru/3.1/library/__main__.html#module-__main__).8990Если имя скрипта ссылается на каталог или zip-файл, имя скрипта добавляется в начало [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path), а файл `__main__.py` из этого каталога выполняется как модуль [`__main__`](https://python-all.ru/3.1/library/__main__.html#module-__main__).9192Если не указана опция интерфейса, подразумевается [*-i*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-i), `sys.argv[0]` является пустой строкой (`""`), а текущий каталог будет добавлен в начало [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path).9394> **См. также**95>96> [*Запуск интерпретатора*](https://python-all.ru/3.1/tutorial/interpreter.html#tut-invoking)9798### 1.1.2. Общие параметры99100#### `-?`101102#### `-h`103104#### `--help`105106Выводит краткое описание всех параметров командной строки.107108#### `-V`109110#### `--version`111112Выводит номер версии Python и завершает работу. Пример вывода:113114```text115Python 3.0116```117118### 1.1.3. Прочие параметры119120#### `-b`121122Выдаёт предупреждение при сравнении str и bytes. Выдаёт ошибку, если опция указана дважды (123124*-bb*125126).127128#### `-B`129130Если указано, Python не будет пытаться записать файлы131132`.pyc`133134или135136`.pyo`137138при импорте исходных модулей. См. также139140[**PYTHONDONTWRITEBYTECODE**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONDONTWRITEBYTECODE)141142.143144#### `-d`145146Включает вывод отладки парсера (только для волшебников, зависит от параметров компиляции). См. также147148[**PYTHONDEBUG**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONDEBUG)149150.151152#### `-E`153154Игнорирует все переменные окружения155156**PYTHON\***157158, например159160[**PYTHONPATH**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONPATH)161162и163164[**PYTHONHOME**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONHOME)165166, которые могут быть установлены.167168#### `-i`169170Если скрипт передан в качестве первого аргумента или используется опция [*-c*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-c), после выполнения скрипта или команды переходит в интерактивный режим, даже если [`sys.stdin`](https://python-all.ru/3.1/library/sys.html#sys.stdin) не является терминалом. Файл [**PYTHONSTARTUP**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONSTARTUP) не читается.171172Это может быть полезно для просмотра глобальных переменных или трассировки стека, когда скрипт вызывает исключение. См. также [**PYTHONINSPECT**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONINSPECT).173174#### `-O`175176Включает базовые оптимизации. Это изменяет расширение файлов для скомпилированных (177178[*байткод*](https://python-all.ru/3.1/glossary.html#term-bytecode)179180) файлов с181182`.pyc`183184на185186`.pyo`187188. См. также189190[**PYTHONOPTIMIZE**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONOPTIMIZE)191192.193194#### `-OO`195196Отбрасывает строки документации в дополнение к оптимизациям197198[*-O*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-O)199200.201202#### `-R`203204Включает рандомизацию хэшей, так что значения [`__hash__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__hash__) объектов str, bytes и datetime засаливаются непредсказуемым случайным значением. Хотя они остаются постоянными в рамках одного процесса Python, они не предсказуемы между повторными вызовами Python.205206Это предназначено для защиты от отказа в обслуживании, вызванного специально подобранными входными данными, которые эксплуатируют наихудшую производительность построения словаря со сложностью O(n^2). См. [http://www.ocert.org/advisories/ocert-2011-003.html](https://python-all.ru/3.1/using/cmdline.html) для подробностей.207208Изменение хэш-значений влияет на порядок, в котором ключи извлекаются из словаря. Хотя Python никогда не давал гарантий относительно этого порядка (и он обычно различается между 32-битными и 64-битными сборками), достаточно много реального кода неявно полагается на это негарантированное поведение, поэтому рандомизация отключена по умолчанию.209210См. также [**PYTHONHASHSEED**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONHASHSEED).211212Новое в версии 3.1.5.213214#### `-s`215216Не добавлять пользовательский каталог site в sys.path217218> **См. также**219>220> [**PEP 370**](https://python-all.ru/3.1/using/cmdline.html) – Каталог site-packages для каждого пользователя221222#### `-S`223224Отключает импорт модуля225226[`site`](https://python-all.ru/3.1/library/site.html#module-site)227228и связанные с сайтом манипуляции с229230[`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path)231232, которые он влечёт.233234#### `-u`235236Принудительно отключает буферизацию двоичного слоя потоков stdin, stdout и stderr (доступного как их атрибут `buffer`). Текстовый слой ввода-вывода по-прежнему будет буферизован построчно.237238См. также [**PYTHONUNBUFFERED**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONUNBUFFERED).239240#### `-v`241242Выводит сообщение каждый раз, когда модуль инициализируется, показывая место (имя файла или встроенный модуль), из которого он загружается. При двойном указании (243244*-vv*245246) выводит сообщение для каждого файла, проверяемого при поиске модуля. Также предоставляет информацию об очистке модулей при завершении. См. также247248[**PYTHONVERBOSE**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONVERBOSE)249250.251252#### `-W arg`253254Управление предупреждениями. Механизм предупреждений Python по умолчанию выводит сообщения предупреждений в [`sys.stderr`](https://python-all.ru/3.1/library/sys.html#sys.stderr). Типичное сообщение предупреждения имеет следующую форму:255256```text257file:line: category: message258```259260По умолчанию каждое предупреждение выводится один раз для каждой строки исходного кода, в которой оно возникает. Этот параметр управляет частотой вывода предупреждений.261262Может быть указано несколько опций [*-W*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-W); если предупреждение соответствует более чем одной опции, выполняется действие для последней подходящей опции. Недействительные опции [*-W*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-W) игнорируются (хотя сообщение предупреждения о недействительных опциях выводится при первом предупреждении).263264Предупреждения также можно контролировать из программы Python с помощью модуля [`warnings`](https://python-all.ru/3.1/library/warnings.html#module-warnings).265266Простейшая форма аргумента – одна из следующих строк действий (или\\nуникальное сокращение):267268**`игнорировать`**269270Игнорировать все предупреждения.271272**`по умолчанию`**273274Явно запросить поведение по умолчанию (вывод каждого предупреждения один раз на\\nстроку исходного кода).275276**`все`**277278Выводить предупреждение при каждом его появлении (это может породить много сообщений, если\\nпредупреждение вызывается многократно для одной и той же строки, например, внутри\\nцикла).279280**`модуль`**281282Выводить каждое предупреждение только при первом появлении в каждом модуле.283284**`однократно`**285286Выводить каждое предупреждение только при первом появлении в программе.287288**`ошибка`**289290Возбуждать исключение вместо вывода предупреждения.291292Полная форма аргумента:293294```text295action:message:category:module:line296```297298Здесь *action* работает как описано выше, но применяется только к сообщениям, соответствующим остальным полям. Пустые поля соответствуют всем значениям; завершающие пустые поля можно опустить. Поле *message* соответствует началу выводимого предупреждения; сравнение регистронезависимо. Поле *category* соответствует категории предупреждения. Оно должно быть именем класса; при сравнении проверяется, является ли фактическая категория предупреждения подклассом указанной категории. Должно быть указано полное имя класса. Поле *module* соответствует полному имени модуля (с точками); сравнение регистрозависимо. Поле *line* соответствует номеру строки, при этом ноль соответствует всем номерам строк и, таким образом, эквивалентен отсутствующему номеру.299300> **См. также**301>302> [`warnings`](https://python-all.ru/3.1/library/warnings.html#module-warnings) – модуль warnings303>304> [**PEP 230**](https://python-all.ru/3.1/using/cmdline.html) – инфраструктура предупреждений305306#### `-x`307308Пропускает первую строку исходного файла, позволяя использовать не-Unix формы `#!cmd`. Это предназначено только для специфичного для DOS хака.309310> **Примечание**311>312> Номера строк в сообщениях об ошибках будут смещены на единицу.313314### 1.1.4. Параметры, которые не следует использовать315316#### `-J`317318Зарезервировано для319320[Jython](https://python-all.ru/3.1/using/cmdline.html)321322.323324#### `-X`325326Зарезервировано для использования альтернативными реализациями Python в собственных целях.327328## 1.2. Переменные окружения329330Эти переменные окружения влияют на поведение Python.331332**`PYTHONHOME`**333334Изменяет расположение стандартных библиотек Python. По умолчанию библиотеки ищутся в `prefix/lib/pythonversion` и `exec_prefix/lib/pythonversion`, где `prefix` и `exec_prefix` – это каталоги, зависящие от установки, оба по умолчанию равны `/usr/local`.335336Если [**PYTHONHOME**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONHOME) задан как одна директория, его значение заменяет и `prefix`, и `exec_prefix`. Чтобы указать для них разные значения, задайте [**PYTHONHOME**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONHOME) как `prefix:exec_prefix`.337338**`PYTHONPATH`**339340Дополняет стандартный путь поиска модулей. Формат такой же, как у **PATH** в оболочке: один или несколько путей к каталогам, разделённых [`os.pathsep`](https://python-all.ru/3.1/library/os.html#os.pathsep) (например, двоеточием в Unix или точкой с запятой в Windows). Несуществующие каталоги игнорируются без предупреждения.341342Помимо обычных каталогов, отдельные записи [**PYTHONPATH**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONPATH) могут указывать на zip-файлы, содержащие чистые модули Python (в исходной или скомпилированной форме). Расширения не могут быть импортированы из zip-файлов.343344Стандартный путь поиска зависит от установки, но обычно начинается с `prefix/lib/pythonversion` (см. [**PYTHONHOME**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONHOME) выше). Он *всегда* добавляется в конец [**PYTHONPATH**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONPATH).345346Дополнительный каталог будет вставлен в путь поиска перед [**PYTHONPATH**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONPATH), как описано выше в разделе [*Параметры интерфейса*](https://python-all.ru/3.1/using/cmdline.html#using-on-interface-options). Путь поиска можно изменять из программы на Python через переменную [`sys.path`](https://python-all.ru/3.1/library/sys.html#sys.path).347348**`PYTHONSTARTUP`**349350Если указано имя читаемого файла, команды Python из этого файла выполняются до отображения первого приглашения в интерактивном режиме. Файл выполняется в том же пространстве имён, что и интерактивные команды, поэтому объекты, определённые или импортированные в нём, могут использоваться без квалификации в интерактивном сеансе. В этом файле также можно изменить приглашения351352[`sys.ps1`](https://python-all.ru/3.1/library/sys.html#sys.ps1)353354и355356[`sys.ps2`](https://python-all.ru/3.1/library/sys.html#sys.ps2)357358.359360**`PYTHONY2K`**361362Если присвоено непустое значение, модуль363364[`time`](https://python-all.ru/3.1/library/time.html#module-time)365366будет требовать, чтобы даты, указанные в виде строк, содержали 4-значные годы; в противном случае 2-значные годы преобразуются по правилам, описанным в документации модуля367368[`time`](https://python-all.ru/3.1/library/time.html#module-time)369370.371372**`PYTHONOPTIMIZE`**373374Если установлена в непустую строку, это эквивалентно указанию опции375376[*-O*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-O)377378. Если установлена в целое число, это эквивалентно указанию379380[*-O*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-O)381382несколько раз.383384**`PYTHONDEBUG`**385386Если установлена в непустую строку, это эквивалентно указанию опции387388[*-d*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-d)389390. Если установлена в целое число, это эквивалентно указанию391392[*-d*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-d)393394несколько раз.395396**`PYTHONINSPECT`**397398Если установлена в непустую строку, это эквивалентно указанию опции [*-i*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-i).399400Эту переменную также можно изменить из кода Python с помощью [`os.environ`](https://python-all.ru/3.1/library/os.html#os.environ), чтобы принудительно включить режим инспекции при завершении программы.401402**`PYTHONUNBUFFERED`**403404Если эта переменная установлена в непустую строку, это эквивалентно указанию опции405406[*-u*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-u)407408.409410**`PYTHONVERBOSE`**411412Если эта переменная установлена в непустую строку, это эквивалентно указанию опции413414[*-v*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-v)415416. Если установлена в целое число, это эквивалентно указанию417418[*-v*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-v)419420несколько раз.421422**`PYTHONCASEOK`**423424Если эта переменная установлена, Python игнорирует регистр в операторах425426[`import`](https://python-all.ru/3.1/reference/simple_stmts.html#import)427428. Это работает только в Windows.429430**`PYTHONDONTWRITEBYTECODE`**431432Если эта переменная установлена, Python не будет пытаться создавать файлы433434`.pyc`435436или437438`.pyo`439440при импорте исходных модулей.441442**`PYTHONHASHSEED`**443444Если для этой переменной установлено значение `random`, эффект будет таким же, как при указании опции [*-R*](https://python-all.ru/3.1/using/cmdline.html#cmdoption-trace-R): для инициализации хешей объектов str, bytes и datetime используется случайное значение.445446Если [**PYTHONHASHSEED**](https://python-all.ru/3.1/using/cmdline.html#envvar-PYTHONHASHSEED) задано целым числом, оно используется как фиксированное зерно для генерации hash() для типов, охваченных рандомизацией хешей.447448Его цель – обеспечить воспроизводимое хеширование, например, для самотестирования самого интерпретатора, или чтобы позволить кластеру процессов Python обмениваться значениями хешей.449450Целое число должно быть десятичным числом в диапазоне \[0,4294967295\]. Указание значения 0 приведёт к тем же значениям хешей, что и при отключённой рандомизации хешей.451452Новое в версии 3.1.5.453454**`PYTHONIOENCODING`**455456Переопределяет кодировку, используемую для stdin/stdout/stderr, в формате `имя_кодировки:обработчик_ошибок`. Часть `:обработчик_ошибок` необязательна и имеет тот же смысл, что и в [`str.encode()`](https://python-all.ru/3.1/library/stdtypes.html#str.encode).457458Для stderr часть `:errorhandler` игнорируется; обработчик всегда будет `'backslashreplace'`.459460**`PYTHONNOUSERSITE`**461462Если эта переменная установлена, Python не будет добавлять каталог пользовательских сайтов в sys.path.463464> **См. также**465>466> [**PEP 370**](https://python-all.ru/3.1/using/cmdline.html) – Каталог site-packages для каждого пользователя467468**`PYTHONUSERBASE`**469470Устанавливает базовый каталог для пользовательского каталога сайтов471472> **См. также**473>474> [**PEP 370**](https://python-all.ru/3.1/using/cmdline.html) – Каталог site-packages для каждого пользователя475476**`PYTHONEXECUTABLE`**477478Если эта переменная окружения установлена,479480`sys.argv[0]`481482будет установлено в её значение вместо значения, полученного через среду выполнения C. Работает только на Mac OS X.483484### 1.2.1. Переменные режима отладки485486Установка этих переменных действует только в отладочной сборке Python, то есть если Python был собран с опцией сборки *--with-pydebug*.487488**`PYTHONTHREADDEBUG`**489490Если установлено, Python будет выводить отладочную информацию о потоках.491492**`PYTHONDUMPREFS`**493494Если установлено, Python будет выгружать объекты и счетчики ссылок, все еще живые после завершения работы интерпретатора.495496**`PYTHONMALLOCSTATS`**497498Если установлено, Python будет выводить статистику распределения памяти каждый раз при создании новой арены объектов, а также при завершении работы.499