Command-line use¶

This module can work as a script (usingpython -m compileall) tocompile Python sources.

directory...¶

file...¶

Positional arguments are files to compile or directories that containsource files, traversed recursively. If no argument is given, behave as ifthe command line was-l<directoriesfromsys.path>.

-l¶

Do not recurse into subdirectories, only compile source code files directlycontained in the named or implied directories.

-f¶

Force rebuild even if timestamps are up-to-date.

-q¶

Do not print the list of files compiled. If passed once, error messages willstill be printed. If passed twice (-qq), all output is suppressed.

-ddestdir¶

Directory prepended to the path to each file being compiled. This willappear in compilation time tracebacks, and is also compiled in to thebyte-code file, where it will be used in tracebacks and other messages incases where the source file does not exist at the time the byte-code file isexecuted.

-sstrip_prefix¶

-pprepend_prefix¶

Remove (-s) or append (-p) the given prefix of pathsrecorded in the.pyc files.Cannot be combined with-d.

-xregex¶

regex is used to search the full path to each file considered forcompilation, and if the regex produces a match, the file is skipped.

-ilist¶

Read the filelist and add each line that it contains to the list offiles and directories to compile. Iflist is-, read lines fromstdin.

-b¶

Write the byte-code files to their legacy locations and names, which mayoverwrite byte-code files created by another version of Python. The defaultis to write files to theirPEP 3147 locations and names, which allowsbyte-code files from multiple versions of Python to coexist.

-r¶

Control the maximum recursion level for subdirectories.If this is given, then-l option will not be taken into account.python -m compileall <directory> -r 0 is equivalent topython -m compileall <directory> -l.

-jN¶

UseN workers to compile the files within the given directory.If0 is used, then the result ofos.process_cpu_count()will be used.

--invalidation-mode[timestamp|checked-hash|unchecked-hash]¶

Control how the generated byte-code files are invalidated at runtime.Thetimestamp value, means that.pyc files with the source timestampand size embedded will be generated. Thechecked-hash andunchecked-hash values cause hash-based pycs to be generated. Hash-basedpycs embed a hash of the source file contents rather than a timestamp. SeeCached bytecode invalidation for more information on how Python validatesbytecode cache files at runtime.The default istimestamp if theSOURCE_DATE_EPOCH environmentvariable is not set, andchecked-hash if theSOURCE_DATE_EPOCHenvironment variable is set.

-olevel¶

Compile with the given optimization level. May be used multiple timesto compile for multiple levels at a time (for example,compileall-o1-o2).

-edir¶

Ignore symlinks pointing outside the given directory.

--hardlink-dupes¶

If two.pyc files with different optimization level havethe same content, use hard links to consolidate duplicate files.

There is no command-line option to control the optimization level used by thecompile() function, because the Python interpreter itself alreadyprovides the option:python -O -m compileall.

Similarly, thecompile() function respects thesys.pycache_prefixsetting. The generated bytecode cache will only be useful ifcompile() isrun with the samesys.pycache_prefix (if any) that will be used atruntime.

Public functions¶

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)¶

Recursively descend the directory tree named bydir, compiling all.pyfiles along the way. Return a true value if all the files compiled successfully,and a false value otherwise.

Themaxlevels parameter is used to limit the depth of the recursion; itdefaults tosys.getrecursionlimit().

Ifddir is given, it is prepended to the path to each file being compiledfor use in compilation time tracebacks, and is also compiled in to thebyte-code file, where it will be used in tracebacks and other messages incases where the source file does not exist at the time the byte-code file isexecuted.

Ifforce is true, modules are re-compiled even if the timestamps are up todate.

Ifrx is given, itssearch method is called on the complete path to eachfile considered for compilation, and if it returns a true value, the fileis skipped. This can be used to exclude files matching a regular expression,given as are.Pattern object.

Ifquiet isFalse or0 (the default), the filenames and otherinformation are printed to standard out. Set to1, only errors areprinted. Set to2, all output is suppressed.

Iflegacy is true, byte-code files are written to their legacy locationsand names, which may overwrite byte-code files created by another version ofPython. The default is to write files to theirPEP 3147 locations andnames, which allows byte-code files from multiple versions of Python tocoexist.

optimize specifies the optimization level for the compiler. It is passed tothe built-incompile() function. Accepts also a sequence of optimizationlevels which lead to multiple compilations of one.py file in one call.

The argumentworkers specifies how many workers are used tocompile files in parallel. The default is to not use multiple workers.If the platform can’t use multiple workers andworkers argument is given,then sequential compilation will be used as a fallback. Ifworkersis 0, the number of cores in the system is used. Ifworkers islower than0, aValueError will be raised.

invalidation_mode should be a member of thepy_compile.PycInvalidationMode enum and controls how the generatedpycs are invalidated at runtime.

Thestripdir,prependdir andlimit_sl_dest arguments correspond tothe-s,-p and-e options described above.They may be specified asstr oros.PathLike.

Ifhardlink_dupes is true and two.pyc files with different optimizationlevel have the same content, use hard links to consolidate duplicate files.

Changed in version 3.2:Added thelegacy andoptimize parameter.

Changed in version 3.5:Added theworkers parameter.

Changed in version 3.5:quiet parameter was changed to a multilevel value.

Changed in version 3.5:Thelegacy parameter only writes out.pyc files, not.pyo filesno matter what the value ofoptimize is.

Changed in version 3.6:Accepts apath-like object.

Changed in version 3.7:Theinvalidation_mode parameter was added.

Changed in version 3.7.2:Theinvalidation_mode parameter’s default value is updated toNone.

Changed in version 3.8:Settingworkers to 0 now chooses the optimal number of cores.

Changed in version 3.9:Addedstripdir,prependdir,limit_sl_dest andhardlink_dupes arguments.Default value ofmaxlevels was changed from10 tosys.getrecursionlimit()

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)¶

Compile the file with pathfullname. Return a true value if the filecompiled successfully, and a false value otherwise.

Ifddir is given, it is prepended to the path to the file being compiledfor use in compilation time tracebacks, and is also compiled in to thebyte-code file, where it will be used in tracebacks and other messages incases where the source file does not exist at the time the byte-code file isexecuted.

Ifrx is given, itssearch method is passed the full path name to thefile being compiled, and if it returns a true value, the file is notcompiled andTrue is returned. This can be used to exclude files matchinga regular expression, given as are.Pattern object.

Ifquiet isFalse or0 (the default), the filenames and otherinformation are printed to standard out. Set to1, only errors areprinted. Set to2, all output is suppressed.

Iflegacy is true, byte-code files are written to their legacy locationsand names, which may overwrite byte-code files created by another version ofPython. The default is to write files to theirPEP 3147 locations andnames, which allows byte-code files from multiple versions of Python tocoexist.

optimize specifies the optimization level for the compiler. It is passed tothe built-incompile() function. Accepts also a sequence of optimizationlevels which lead to multiple compilations of one.py file in one call.

invalidation_mode should be a member of thepy_compile.PycInvalidationMode enum and controls how the generatedpycs are invalidated at runtime.

Thestripdir,prependdir andlimit_sl_dest arguments correspond tothe-s,-p and-e options described above.They may be specified asstr oros.PathLike.

Ifhardlink_dupes is true and two.pyc files with different optimizationlevel have the same content, use hard links to consolidate duplicate files.

Added in version 3.2.

Changed in version 3.5:quiet parameter was changed to a multilevel value.

Changed in version 3.5:Thelegacy parameter only writes out.pyc files, not.pyo filesno matter what the value ofoptimize is.

Changed in version 3.7:Theinvalidation_mode parameter was added.

Changed in version 3.7.2:Theinvalidation_mode parameter’s default value is updated toNone.

Changed in version 3.9:Addedstripdir,prependdir,limit_sl_dest andhardlink_dupes arguments.

compileall.compile_path(skip_curdir=True,maxlevels=0,force=False,quiet=0,legacy=False,optimize=-1,invalidation_mode=None)¶

Byte-compile all the.py files found alongsys.path. Return atrue value if all the files compiled successfully, and a false value otherwise.

Ifskip_curdir is true (the default), the current directory is not includedin the search. All other parameters are passed to thecompile_dir()function. Note that unlike the other compile functions,maxlevelsdefaults to0.

Changed in version 3.2:Added thelegacy andoptimize parameter.

Changed in version 3.5:quiet parameter was changed to a multilevel value.

Changed in version 3.5:Thelegacy parameter only writes out.pyc files, not.pyo filesno matter what the value ofoptimize is.

Changed in version 3.7:Theinvalidation_mode parameter was added.

Changed in version 3.7.2:Theinvalidation_mode parameter’s default value is updated toNone.

To force a recompile of all the.py files in theLib/subdirectory and all its subdirectories:

importcompileallcompileall.compile_dir('Lib/',force=True)# Perform same compilation, excluding files in .svn directories.importrecompileall.compile_dir('Lib/',rx=re.compile(r'[/\\][.]svn'),force=True)# pathlib.Path objects can also be used.importpathlibcompileall.compile_dir(pathlib.Path('Lib/'),force=True)