compileall.md

1> **Источник:** https://python-all.ru/3.13/library/compileall.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `compileall` – байт-компиляция библиотек Python89**Исходный код:** [Lib/compileall.py](https://python-all.ru/src/3.13/Lib/compileall.py)1011---1213Этот модуль предоставляет несколько утилитных функций для поддержки установки библиотек Python. Эти функции компилируют исходные файлы Python в дереве каталогов. Модуль можно использовать для создания кэшированных файлов байт-кода во время установки библиотеки, что делает их доступными для использования даже пользователями, у которых нет прав на запись в библиотечные каталоги.1415[Доступность](https://python-all.ru/3.13/library/intro.html#availability): не WASI.1617Этот модуль не работает или недоступен на WebAssembly. Подробнее см. [платформы WebAssembly](https://python-all.ru/3.13/library/intro.html#wasm-availability).1819## Использование в командной строке2021Этот модуль может работать как скрипт (используя **python -m compileall**) для компиляции исходников Python.2223#### `directory ...`2425#### `file ...`2627Позиционные аргументы – это файлы для компиляции или каталоги, содержащие исходные файлы, которые обходятся рекурсивно. Если аргументы не указаны, поведение эквивалентно командной строке `-l <directories from sys.path>`.2829#### `-l`3031Не рекурсивно обходить подкаталоги, а компилировать только исходные файлы, непосредственно содержащиеся в указанных или подразумеваемых каталогах.3233#### `-f`3435Принудительная пересборка, даже если метки времени актуальны.3637#### `-q`3839Не печатать список скомпилированных файлов. Если указан один раз, сообщения об ошибках все равно будут выводиться. Если указан дважды (`-qq`), весь вывод подавляется.4041#### `-d destdir`4243Каталог, добавляемый в начало пути к каждому компилируемому файлу. Он будет отображаться в трассировках во время компиляции, а также будет встроен в файл байт-кода, где будет использоваться в трассировках и других сообщениях в случаях, когда исходный файл не существует на момент выполнения файла байт-кода.4445#### `-s strip_prefix`4647Удаляет указанный префикс из путей, записанных в файлах `.pyc`. Пути делаются относительными относительно префикса.4849Этот параметр можно использовать с `-p`, но не с `-d`.5051#### `-p prepend_prefix`5253Добавляет указанный префикс в начало путей, записанных в файлах `.pyc`. Используйте `-p /`, чтобы сделать пути абсолютными.5455Этот параметр можно использовать с `-s`, но не с `-d`.5657#### `-x regex`5859Регулярное выражение используется для поиска в полном пути каждого файла, рассматриваемого для компиляции, и если есть совпадение, файл пропускается.6061#### `-i list`6263Читает файл `list` и добавляет каждую строку из него в список файлов и каталогов для компиляции. Если `list` равно `-`, строки читаются из `stdin`.6465#### `-b`6667Записывает файлы байт-кода в их устаревшие расположения и имена, что может перезаписать файлы байт-кода, созданные другой версией Python. По умолчанию файлы записываются в расположения и имена согласно [**PEP 3147**](https://python-all.ru/3.13/library/compileall.html), что позволяет файлам байт-кода от нескольких версий Python сосуществовать.6869#### `-r`7071Управляет максимальным уровнем рекурсии для подкаталогов. Если этот параметр указан, то опция `-l` не принимается во внимание. **python -m compileall \<directory\> -r 0** эквивалентно **python -m compileall \<directory\> -l**.7273#### `-j N`7475Используется *N* рабочих для компиляции файлов в указанном каталоге. Если используется `0`, то будет использован результат [`os.process_cpu_count()`](https://python-all.ru/3.13/library/os.html#os.process_cpu_count).7677#### `--invalidation-mode [timestamp|checked-hash|unchecked-hash]`7879Управление тем, как сгенерированные файлы байт-кода становятся недействительными во время выполнения. Значение `timestamp` означает, что будут созданы файлы `.pyc` с встроенными временной меткой и размером исходного файла. Значения `checked-hash` и `unchecked-hash` вызывают создание pyc на основе хеша. Pyc на основе хеша содержат хеш содержимого исходного файла, а не временную метку. См. [Инвалидация кэшированного байт-кода](https://python-all.ru/3.13/reference/import.html#pyc-invalidation) для получения дополнительной информации о том, как Python проверяет файлы кэша байт-кода во время выполнения. По умолчанию используется `timestamp`, если переменная окружения `SOURCE_DATE_EPOCH` не установлена, и `checked-hash`, если переменная окружения `SOURCE_DATE_EPOCH` установлена.8081#### `-o level`8283Компиляция с заданным уровнем оптимизации. Может использоваться несколько раз для компиляции сразу для нескольких уровней (например, `compileall -o 1 -o 2`).8485#### `-e dir`8687Игнорировать символические ссылки, указывающие за пределы указанного каталога.8889#### `--hardlink-dupes`9091Если два файла `.pyc` с разными уровнями оптимизации имеют одинаковое содержимое, используются жёсткие ссылки для объединения дублирующихся файлов.9293Изменено в версии 3.2: Добавлены опции `-i`, `-b` и `-h`.9495Изменено в версии 3.5: Добавлены опции `-j`, `-r` и `-qq`. Опция `-q` была изменена на многоуровневое значение. `-b` всегда будет создавать файл байт-кода с расширением `.pyc`, а не `.pyo`.9697Изменено в версии 3.7: Добавлена опция `--invalidation-mode`.9899Изменено в версии 3.9: Добавлены опции `-s`, `-p`, `-e` и `--hardlink-dupes`. Увеличено ограничение рекурсии по умолчанию с 10 до [`sys.getrecursionlimit()`](https://python-all.ru/3.13/library/sys.html#sys.getrecursionlimit). Добавлена возможность указывать опцию `-o` несколько раз.100101Не существует опции командной строки для управления уровнем оптимизации, используемым функцией [`compile()`](https://python-all.ru/3.13/library/functions.html#compile), поскольку сам интерпретатор Python уже предоставляет такую возможность: **python -O -m compileall**.102103Аналогично, функция [`compile()`](https://python-all.ru/3.13/library/functions.html#compile) учитывает настройку [`sys.pycache_prefix`](https://python-all.ru/3.13/library/sys.html#sys.pycache_prefix). Сгенерированный кэш байт-кода будет полезен только в том случае, если `compile()` запускается с тем же `sys.pycache_prefix` (если он есть), который будет использоваться во время выполнения.104105## Публичные функции106107#### `compileall.compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)`108109Рекурсивно обходит дерево каталогов, указанное параметром *dir*, компилируя все файлы `.py` по пути. Возвращает истинное значение, если все файлы скомпилированы успешно, и ложное в противном случае.110111Параметр *maxlevels* используется для ограничения глубины рекурсии; по умолчанию он равен `sys.getrecursionlimit()`.112113Если указан параметр *ddir*, он добавляется в начало пути к каждому компилируемому файлу для использования в трассировках во время компиляции, а также компилируется в файл байт-кода, где будет использоваться в трассировках и других сообщениях в случаях, когда исходный файл не существует на момент выполнения файла байт-кода.114115Если *force* равен true, модули перекомпилируются, даже если временные метки актуальны.116117Если указан *rx*, его метод `search` вызывается для полного пути к каждому файлу, рассматриваемому для компиляции, и если он возвращает истинное значение, файл пропускается. Это можно использовать для исключения файлов, соответствующих регулярному выражению, заданному в виде объекта [re.Pattern](https://python-all.ru/3.13/library/re.html#re-objects).118119Если *quiet* равен `False` или `0` (по умолчанию), имена файлов и другая информация выводятся в стандартный поток вывода. При значении `1` выводятся только ошибки. При значении `2` весь вывод подавляется.120121Если *legacy* истинен, файлы байт-кода записываются в их устаревшие расположения и имена, что может перезаписать файлы байт-кода, созданные другой версией Python. По умолчанию файлы записываются в их расположения и имена [**PEP 3147**](https://python-all.ru/3.13/library/compileall.html), что позволяет файлам байт-кода от разных версий Python сосуществовать.122123*optimize* задаёт уровень оптимизации для компилятора. Он передаётся встроенной функции [`compile()`](https://python-all.ru/3.13/library/functions.html#compile). Также принимает последовательность уровней оптимизации, которая приводит к многократной компиляции одного файла `.py` за один вызов.124125Аргумент *workers* указывает, сколько рабочих процессов используется для параллельной компиляции файлов. По умолчанию несколько рабочих процессов не используются. Если платформа не может использовать несколько рабочих процессов и указан аргумент *workers*, то в качестве запасного варианта используется последовательная компиляция. Если *workers* равен 0, используется количество ядер в системе. Если *workers* меньше `0`, будет возбуждено [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError).126127*invalidation\_mode* должен быть элементом перечисления [`py_compile.PycInvalidationMode`](https://python-all.ru/3.13/library/py_compile.html#py_compile.PycInvalidationMode) и управляет тем, как сгенерированные pyc-файлы становятся недействительными во время выполнения.128129Аргументы *stripdir*, *prependdir* и *limit\_sl\_dest* соответствуют опциям `-s`, `-p` и `-e`, описанным выше. Их можно задавать как `str` или [`os.PathLike`](https://python-all.ru/3.13/library/os.html#os.PathLike).130131Если *hardlink\_dupes* истинен и два файла `.pyc` с разным уровнем оптимизации имеют одинаковое содержимое, используются жёсткие ссылки для объединения дублирующихся файлов.132133Изменено в версии 3.2: Добавлены параметры *legacy* и *optimize*.134135Изменено в версии 3.5: Добавлен параметр *workers*.136137Изменено в версии 3.5: Параметр *quiet* изменён на многоуровневое значение.138139Изменено в версии 3.5: Параметр *legacy* записывает только файлы `.pyc`, а не `.pyo` независимо от значения *optimize*.140141Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.13/glossary.html#term-path-like-object).142143Изменено в версии 3.7: Добавлен параметр *invalidation\_mode*.144145Изменено в версии 3.7.2: Значение по умолчанию параметра *invalidation\_mode* обновлено до `None`.146147Изменено в версии 3.8: Установка *workers* в 0 теперь выбирает оптимальное количество ядер.148149Изменено в версии 3.9: Добавлены аргументы *stripdir*, *prependdir*, *limit\_sl\_dest* и *hardlink\_dupes*. Значение по умолчанию *maxlevels* изменено с `10` на `sys.getrecursionlimit()`150151#### `compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)`152153Компилирует файл с путём *fullname*. Возвращает истинное значение, если файл скомпилирован успешно, и ложное значение в противном случае.154155Если указан *ddir*, он добавляется в начало пути к компилируемому файлу для использования в трассировках во время компиляции, а также встраивается в файл байт-кода, где будет использоваться в трассировках и других сообщениях в случаях, когда исходный файл не существует на момент выполнения файла байт-кода.156157Если указан *rx*, его методу `search` передаётся полный путь к компилируемому файлу, и если он возвращает истинное значение, файл не компилируется и возвращается `True`. Это можно использовать для исключения файлов, соответствующих регулярному выражению, заданному в виде объекта [re.Pattern](https://python-all.ru/3.13/library/re.html#re-objects).158159Если *quiet* равен `False` или `0` (по умолчанию), имена файлов и другая информация выводятся в стандартный поток вывода. При значении `1` выводятся только ошибки. При значении `2` весь вывод подавляется.160161Если *legacy* истинен, файлы байт-кода записываются в их устаревшие расположения и имена, что может перезаписать файлы байт-кода, созданные другой версией Python. По умолчанию файлы записываются в их расположения и имена [**PEP 3147**](https://python-all.ru/3.13/library/compileall.html), что позволяет файлам байт-кода от разных версий Python сосуществовать.162163*optimize* задаёт уровень оптимизации для компилятора. Он передаётся встроенной функции [`compile()`](https://python-all.ru/3.13/library/functions.html#compile). Также принимает последовательность уровней оптимизации, которая приводит к многократной компиляции одного файла `.py` за один вызов.164165*invalidation\_mode* должен быть элементом перечисления [`py_compile.PycInvalidationMode`](https://python-all.ru/3.13/library/py_compile.html#py_compile.PycInvalidationMode) и управляет тем, как сгенерированные pyc-файлы становятся недействительными во время выполнения.166167Аргументы *stripdir*, *prependdir* и *limit\_sl\_dest* соответствуют опциям `-s`, `-p` и `-e`, описанным выше. Их можно задавать как `str` или [`os.PathLike`](https://python-all.ru/3.13/library/os.html#os.PathLike).168169Если *hardlink\_dupes* истинен и два файла `.pyc` с разным уровнем оптимизации имеют одинаковое содержимое, используются жёсткие ссылки для объединения дублирующихся файлов.170171Добавлено в версии 3.2.172173Изменено в версии 3.5: Параметр *quiet* изменён на многоуровневое значение.174175Изменено в версии 3.5: Параметр *legacy* записывает только файлы `.pyc`, а не `.pyo` независимо от значения *optimize*.176177Изменено в версии 3.7: Добавлен параметр *invalidation\_mode*.178179Изменено в версии 3.7.2: Значение по умолчанию параметра *invalidation\_mode* обновлено до `None`.180181Изменено в версии 3.9: Добавлены аргументы *stripdir*, *prependdir*, *limit\_sl\_dest* и *hardlink\_dupes*.182183#### `compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)`184185Байт-компилирует все файлы `.py`, найденные вдоль `sys.path`. Возвращает истинное значение, если все файлы скомпилированы успешно, и ложное значение в противном случае.186187Если *skip\_curdir* истинен (по умолчанию), текущий каталог не включается в поиск. Все остальные параметры передаются функции [`compile_dir()`](https://python-all.ru/3.13/library/compileall.html#compileall.compile_dir). Обратите внимание, что в отличие от других функций компиляции, `maxlevels` по умолчанию равен `0`.188189Изменено в версии 3.2: Добавлены параметры *legacy* и *optimize*.190191Изменено в версии 3.5: Параметр *quiet* изменён на многоуровневое значение.192193Изменено в версии 3.5: Параметр *legacy* записывает только файлы `.pyc`, а не `.pyo` независимо от значения *optimize*.194195Изменено в версии 3.7: Добавлен параметр *invalidation\_mode*.196197Изменено в версии 3.7.2: Значение по умолчанию параметра *invalidation\_mode* обновлено до `None`.198199Чтобы принудительно перекомпилировать все файлы `.py` в подкаталоге `Lib/` и всех его подкаталогах:200201```python202import compileall203204compileall.compile_dir('Lib/', force=True)205206# Выполнить ту же компиляцию, исключая файлы в каталогах .svn.207import re208compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)209210# Объекты pathlib.Path также можно использовать.211import pathlib212compileall.compile_dir(pathlib.Path('Lib/'), force=True)213```214215> **См. также**216>217> **Модуль [`py_compile`](https://python-all.ru/3.13/library/py_compile.html#module-py_compile)**218>219> Байт-компилирует один исходный файл.220