Understanding PyInstaller Hooks¶

Note

We strongly encourage package developers to provide hooks with their packages. See section Providing PyInstaller Hooks with your Package for how easy this is.

In summary, a “hook” file extends PyInstaller to adapt it to the special needs and methods used by a Python package. The word “hook” is used for two kinds of files. A runtime hook helps the bootloader to launch an app. For more on runtime hooks, see Changing Runtime Behavior. Other hooks run while an app is being analyzed. They help the Analysis phase find needed files.

The majority of Python packages use normal methods of importing their dependencies, and PyInstaller locates all their files without difficulty. But some packages make unusual uses of the Python import mechanism, or make clever changes to the import system at runtime. For this or other reasons, PyInstaller cannot reliably find all the needed files, or may include too many files. A hook can tell about additional source files or data files to import, or files not to import.

A hook file is a Python script, and can use all Python features. It can also import helper methods from PyInstaller.utils.hooks and useful variables from PyInstaller.compat. These helpers are documented below.

The name of a hook file is hook-full.import.name.py, where full.import.name is the fully-qualified name of an imported script or module. You can browse through the existing hooks in the hooks folder of the PyInstaller distribution folder and see the names of the packages for which hooks have been written. For example hook-PyQt5.QtCore.py is a hook file telling about hidden imports needed by the module PyQt5.QtCore. When your script contains import PyQt5.QtCore (or from PyQt5 import QtCore), Analysis notes that hook-PyQt5.QtCore.py exists, and will call it.

Many hooks consist of only one statement, an assignment to hiddenimports. For example, the hook for the dnspython package, called hook-dns.rdata.py, has only this statement:

hiddenimports = [
    "dns.rdtypes.*",
    "dns.rdtypes.ANY.*"
]

When Analysis sees import dns.rdata or from dns import rdata it calls hook-dns.rdata.py and examines its value of hiddenimports. As a result, it is as if your source script also contained:

import dns.rdtypes.*
import dsn.rdtypes.ANY.*

A hook can also cause the addition of data files, and it can cause certain files to not be imported. Examples of these actions are shown below.

When the module that needs these hidden imports is useful only to your project, store the hook file(s) somewhere near your source file. Then specify their location to the pyinstaller or pyi-makespec command with the --additional-hooks-dir option. If the hook file(s) are at the same level as the script, the command could be simply:

pyinstaller --additional-hooks-dir=. myscript.py

If you write a hook for a module used by others, please ask the package developer to include the hook with her/his package or send us the hook file so we can make it available.

How a Hook Is Loaded¶

A hook is a module named hook-full.import.name.py in a folder where the Analysis object looks for hooks. Each time Analysis detects an import, it looks for a hook file with a matching name. When one is found, Analysis imports the hook’s code into a Python namespace. This results in the execution of all top-level statements in the hook source, for example import statements, assignments to global names, and function definitions. The names defined by these statements are visible to Analysis as attributes of the namespace.

Thus a hook is a normal Python script and can use all normal Python facilities. For example it could test sys.version and adjust its assignment to hiddenimports based on that. There are many hooks in the PyInstaller installation, but a much larger collection can be found in the community hooks package. Please browse through them for examples.

Providing PyInstaller Hooks with your Package¶

As a package developer you can provide hooks for PyInstaller within your package. This has the major benefit that you can easily adopt the hooks when your package changes. Thus your package’s users don’t need to wait until PyInstaller might catch up with these changes. If both PyInstaller and your package provide hooks for some module, your package’s hooks take precedence, but can still be overridden by the command line option --additional-hooks-dir.

You can tell PyInstaller about the additional hooks by defining some simple setuptools entry-points in your package. Therefore add entries like these to your setup.cfg:

[options.entry_points]
pyinstaller40 =
  hook-dirs = pyi_hooksample.__pyinstaller:get_hook_dirs
  tests     = pyi_hooksample.__pyinstaller:get_PyInstaller_tests

This defines two entry-points:

pyinstaller40.hook-dirs for hook registration

This entry point refers to a function that will be invoked with no parameters. It must return a sequence of strings, each element of which provides an additional absolute path to search for hooks. This is equivalent to passing the --additional-hooks-dir command-line option to PyInstaller for each string in the sequence.

In this example, the function is get_hook_dirs() -> List[str].

pyinstaller40.tests for test registration

This entry point refers to a function that will be invoked with no parameters. It must return a sequence of strings, each element of which provides an additional absolute path to a directory tree or to a Python source file. These paths are then passed to pytest for test discovery. This allows both testing by this package and by PyInstaller.

In this project, the function is get_PyInstaller_tests() -> List[str].

A sample project providing a guide for integrating PyInstaller hooks and tests into a package is available at https://github.com/pyinstaller/hooksample. This project demonstrates defining a library which includes PyInstaller hooks along with tests for those hooks and sample file for integration into CD/CI testing. Detailed documentation about this sample project is available at https://pyinstaller-sample-hook.readthedocs.io/en/latest/.

Hook Global Variables¶

A majority of the existing hooks consist entirely of assignments of values to one or more of the following global variables. If any of these are defined by the hook, Analysis takes their values and applies them to the bundle being created.

hiddenimports

A list of module names (relative or absolute) that should be part of the bundled app. This has the same effect as the --hidden-import command line option, but it can contain a list of names and is applied automatically only when the hooked module is imported. Example:

hiddenimports = ['_gdbm', 'socket', 'h5py.defs']

excludedimports

A list of absolute module names that should not be part of the bundled app. If an excluded module is imported only by the hooked module or one of its sub-modules, the excluded name and its sub-modules will not be part of the bundle. (If an excluded name is explicitly imported in the source file or some other module, it will be kept.) Several hooks use this to prevent automatic inclusion of the tkinter module. Example:

excludedimports = ['tkinter']

datas

A list of files to bundle with the app as data. Each entry in the list is a tuple containing two strings. The first string specifies a file (or file “glob”) in this system, and the second specifies the name(s) the file(s) are to have in the bundle. (This is the same format as used for the datas= argument, see Adding Data Files.) Example:

datas = [ ('/usr/share/icons/education_*.png', 'icons') ]

If you need to collect multiple directories or nested directories, you can use helper functions from the PyInstaller.utils.hooks module (see below) to create this list, for example:

datas  = collect_data_files('submodule1')
datas += collect_data_files('submodule2')

In rare cases you may need to apply logic to locate particular files within the file system, for example because the files are in different places on different platforms or under different versions. Then you can write a hook() function as described below under The hook(hook_api) Function.

binaries

A list of files or directories to bundle as binaries. The format is the same as datas (tuples with strings that specify the source and the destination). Binaries is a special case of datas, in that PyInstaller will check each file to see if it depends on other dynamic libraries. Example:

binaries = [ ('C:\\Windows\\System32\\*.dll', 'dlls') ]

Many hooks use helpers from the PyInstaller.utils.hooks module to create this list (see below):

binaries = collect_dynamic_libs('zmq')

Useful Items in `PyInstaller.compat`¶

Various classes and functions to provide some backwards-compatibility with previous versions of Python onward.

A hook may import the following names from PyInstaller.compat, for example:

from PyInstaller.compat import base_prefix, is_win

is_py36, is_py37, is_py38, is_py39, is_py310: True when the current version of Python is at least 3.6, 3.7, 3.8, 3.9, or 3.10, respectively.

is_win¶: True in a Windows system.

is_cygwin¶: True when sys.platform == 'cygwin'.

is_darwin¶: True in Mac OS X.

is_linux¶: True in any GNU/Linux system.

is_solar¶: True in Solaris.

is_aix¶: True in AIX.

is_freebsd¶: True in FreeBSD.

is_openbsd¶: True in OpenBSD.

is_venv¶: True in any virtual environment (either virtualenv or venv).

base_prefix¶: String, the correct path to the base Python installation, whether the installation is native or a virtual environment.

EXTENSION_SUFFIXES¶: List of Python C-extension file suffixes. Used for finding all binary dependencies in a folder; see hook-cryptography.py for an example.

Useful Items in `PyInstaller.utils.hooks`¶

A hook may import useful functions from PyInstaller.utils.hooks. Use a fully-qualified import statement, for example:

from PyInstaller.utils.hooks import collect_data_files, eval_statement

The functions listed here are generally useful and used in a number of existing hooks.

exec_statement(statement)¶

Execute a single Python statement in an externally-spawned interpreter, and return the resulting standard output as a string.

Examples:

tk_version = exec_statement("from _tkinter import TK_VERSION; print(TK_VERSION)")

mpl_data_dir = exec_statement("import matplotlib; print(matplotlib.get_data_path())")
datas = [ (mpl_data_dir, "") ]

eval_statement(statement)¶

Execute a single Python statement in an externally-spawned interpreter, and eval() its output (if any).

Example:

databases = eval_statement('''
   import sqlalchemy.databases
   print(sqlalchemy.databases.__all__)
   ''')
for db in databases:
   hiddenimports.append("sqlalchemy.databases." + db)

is_module_satisfies(requirements, version=None, version_attr='__version__')¶

Test if a PEP 0440 requirement is installed.

Parameters

requirements (str) – Requirements in pkg_resources.Requirements.parse() format.
version (str) – Optional PEP 0440-compliant version (e.g., 3.14-rc5) to be used _instead_ of the current version of this module. If non-None, this function ignores all setuptools distributions for this module and instead compares this version against the version embedded in the passed requirements. This ignores the module name embedded in the passed requirements, permitting arbitrary versions to be compared in a robust manner. See examples below.
version_attr (str) – Optional name of the version attribute defined by this module, defaulting to __version__. If a setuptools distribution exists for this module (it usually does) _and_ the version parameter is None (it usually is), this parameter is ignored.

Returns

Boolean result of the desired validation.

Return type

bool

Raises

AttributeError – If no setuptools distribution exists for this module _and_ this module defines no attribute whose name is the passed version_attr parameter.
ValueError – If the passed specification does _not_ comply with pkg_resources.Requirements syntax.

Examples

# Assume PIL 2.9.0, Sphinx 1.3.1, and SQLAlchemy 0.6 are all installed.
>>> from PyInstaller.utils.hooks import is_module_satisfies
>>> is_module_satisfies('sphinx >= 1.3.1')
True
>>> is_module_satisfies('sqlalchemy != 0.6')
False

>>> is_module_satisfies('sphinx >= 1.3.1; sqlalchemy != 0.6')
False

# Compare two arbitrary versions. In this case, the module name "sqlalchemy" is simply ignored.
>>> is_module_satisfies('sqlalchemy != 0.6', version='0.5')
True

# Since the "pillow" project providing PIL publishes its version via the custom "PILLOW_VERSION" attribute
# (rather than the standard "__version__" attribute), an attribute name is passed as a fallback to validate PIL
# when not installed by setuptools. As PIL is usually installed by setuptools, this optional parameter is
# usually ignored.
>>> is_module_satisfies('PIL == 2.9.0', version_attr='PILLOW_VERSION')
True

See also

pkg_resources.Requirements for the syntax details.

collect_all(package_name, include_py_files=True, filter_submodules=None, exclude_datas=None, include_datas=None)¶

Collect everything for a given package name.

Parameters

package_name – An import-able package name.
include_py_files – Forwarded to collect_data_files().
filter_submodules – Forwarded to collect_submodules().
exclude_datas – Forwarded to collect_data_files().
include_datas – Forwarded to collect_data_files().

Returns

A (datas, binaries, hiddenimports) triplet containing:

All data files, raw Python files (if include_py_files), and package metadata folders.
All dynamic libraries as returned by collect_dynamic_libs().
All submodules of packagename and its dependencies.

Return type

tuple

Typical use:

datas, binaries, hiddenimports = collect_all('my_module_name')

collect_submodules(package, filter=<function <lambda>>)¶

List all submodules of a given package.

Parameters

package (str) – An import-able package.
filter (Callable[[str], bool]) – Filter the submodules found: A callable that takes a submodule name and returns True if it should be included.

Returns

All submodules to be assigned to hiddenimports in a hook.

This function is intended to be used by hook scripts, not by main PyInstaller code.

Examples:

# Collect all submodules of Sphinx don't contain the word ``test``.
hiddenimports = collect_submodules("Sphinx", filter=lambda name: 'test' not in name)

is_module_or_submodule(name, mod_or_submod)¶

This helper function is designed for use in the filter argument of collect_submodules(), by returning True if the given name is a module or a submodule of mod_or_submod.

Examples

The following excludes foo.test and foo.test.one but not foo.testifier.

collect_submodules('foo', lambda name: not is_module_or_submodule(name, 'foo.test'))``

collect_data_files(package, include_py_files=False, subdir=None, excludes=None, includes=None)¶

This function produces a list of (source, dest) non-Python (i.e., data) files that reside in package. Its output can be directly assigned to datas in a hook script; for example, see hook-sphinx.py. Parameters:

The package parameter is a string which names the package.
By default, all Python executable files (those ending in .py, .pyc, and so on) will NOT be collected; setting the include_py_files argument to True collects these files as well. This is typically used with Python functions (such as those in pkgutil) that search a given directory for Python executable files and load them as extensions or plugins.
The subdir argument gives a subdirectory relative to package to search, which is helpful when submodules are imported at run-time from a directory lacking __init__.py.
The excludes argument contains a sequence of strings or Paths. These provide a list of globs to exclude from the collected data files; if a directory matches the provided glob, all files it contains will be excluded as well. All elements must be relative paths, which are relative to the provided package’s path (/ subdir if provided).

Therefore, *.txt will exclude only .txt files in package‘s path, while **/*.txt will exclude all .txt files in package‘s path and all its subdirectories. Likewise, **/__pycache__ will exclude all files contained in any subdirectory named __pycache__.
The includes function like excludes, but only include matching paths. excludes override includes: a file or directory in both lists will be excluded.

This function does not work on zipped Python eggs.

This function is intended to be used by hook scripts, not by main PyInstaller code.

collect_dynamic_libs(package, destdir=None)¶

This function produces a list of (source, dest) of dynamic library files that reside in package. Its output can be directly assigned to binaries in a hook script. The package parameter must be a string which names the package.

Parameters: destdir – Relative path to ./dist/APPNAME where the libraries should be put.

get_module_file_attribute(package)¶

Get the absolute path of the module with the passed name.

Since modules cannot be directly imported during analysis, this function spawns a subprocess importing the module and returning the value of its __file__ attribute.

Parameters: package (str) – Fully-qualified name of this module.
Returns: Absolute path of this module.
Return type: str

get_package_paths(package)¶: Given a package, return the path to packages stored on this machine and also returns the path to this particular package. For example, if pkg.subpkg lives in /abs/path/to/python/libs, then this function returns (/abs/path/to/python/libs, /abs/path/to/python/libs/pkg/subpkg).

copy_metadata(package_name, recursive=False)¶

Collect distribution metadata so that pkg_resources.get_distribution() can find it.

This function returns a list to be assigned to the datas global variable. This list instructs PyInstaller to copy the metadata for the given package to the frozen application’s data directory.

Parameters

package_name (str) – Specifies the name of the package for which metadata should be copied.
recursive (bool) – If true, collect metadata for the package’s dependencies too. This enables use of pkg_resources.require('package') inside the frozen application.

Returns

This should be assigned to datas.

Return type

list

Examples

>>> from PyInstaller.utils.hooks import copy_metadata
>>> copy_metadata('sphinx')
[('c:\python27\lib\site-packages\Sphinx-1.3.2.dist-info',
  'Sphinx-1.3.2.dist-info')]

Some packages rely on metadata files accessed through the pkg_resources module. Normally PyInstaller does not include these metadata files. If a package fails without them, you can use this function in a hook file to easily add them to the frozen bundle. The tuples in the returned list have two strings. The first is the full pathname to a folder in this system. The second is the folder name only. When these tuples are added to datas, the folder will be bundled at the top level.

Changed in version 4.3.1: Prevent dist-info metadata folders being renamed to egg-info which broke pkg_resources.require with extras (see #3033).

Changed in version 4.4.0: Add the recursive option.

collect_entry_point(name)¶

Collect modules and metadata for all exporters of a given entry point.

Parameters: name (str) – The name of the entry point. Check the documentation for the library that uses the entry point to find its name.
Return type: Tuple[list, list]
Returns: A (datas, hiddenimports) pair that should be assigned to the datas and hiddenimports, respectively.

For libraries, such as pytest or keyring, that rely on plugins to extend their behaviour.

Examples

Pytest uses an entry point called 'pytest11' for its extensions. To collect all those extensions use:

datas, hiddenimports = collect_entry_point("pytest11")

These values may be used in a hook or added to the datas and hiddenimports arguments in the .spec file. See Using Spec Files.

New in version 4.3.

get_homebrew_path(formula='')¶

Return the homebrew path to the requested formula, or the global prefix when called with no argument.

Returns the path as a string or None if not found.

Support for Conda¶

Additional helper methods for working specifically with Anaconda distributions are found at PyInstaller.utils.hooks.conda_support which is designed to mimic (albeit loosely) the importlib.metadata package. These functions find and parse the distribution metadata from json files located in the conda-meta directory.

New in version 4.2.0.

This module is available only if run inside a Conda environment. Usage of this module should therefore be wrapped in a conditional clause:

from PyInstaller.utils.hooks import is_pure_conda

if is_pure_conda:
    from PyInstaller.utils.hooks import conda_support

    # Code goes here. e.g.
    binaries = conda_support.collect_dynamic_libs("numpy")
    ...

Packages are all referenced by the distribution name you use to install it, rather than the package name you import it with. I.e., use distribution("pillow") instead of distribution("PIL") or use package_distribution("PIL").

distribution(name)¶

Get distribution information for a given distribution name (i.e., something you would conda install).

Return type: Distribution

package_distribution(name)¶

Get distribution information for a package (i.e., something you would import).

Return type: Distribution

For example, the package pkg_resources belongs to the distribution setuptools, which contains three packages.

>>> package_distribution("pkg_resources")
Distribution(name="setuptools",
             packages=['easy_install', 'pkg_resources', 'setuptools'])

files(name, dependencies=False, excludes=None)¶

List all files belonging to a distribution.

Parameters

name (str) – The name of the distribution.
dependencies – Recursively collect files of dependencies too.
excludes – Distributions to ignore if dependencies is true.

Return type

List[PackagePath]

Returns

All filenames belonging to the given distribution.

With dependencies=False, this is just a shortcut for:

conda_support.distribution(name).files

requires(name, strip_versions=False)¶

List requirements of a distribution.

Parameters

name (str) – The name of the distribution.
strip_versions – List only their names, not their version constraints.

Return type

List[str]

Returns

A list of distribution names.

class Distribution(json_path)¶

A bucket class representation of a Conda distribution.

This bucket exports the following attributes:

Variables

name – The distribution’s name.
version – Its version.
files – All filenames as PackagePath()s included with this distribution.
dependencies – Names of other distributions that this distribution depends on (with version constraints removed).
packages – Names of importable packages included in this distribution.

This class is not intended to be constructed directly by users. Rather use distribution() or package_distribution() to provide one for you.

class PackagePath(*args)¶

A filename relative to Conda’s root (sys.prefix).

This class inherits from pathlib.PurePosixPath even on non-Posix OSs. To convert to a pathlib.Path pointing to the real file, use the locate() method.

locate()¶: Return a path-like object for this path pointing to the file’s true location.

walk_dependency_tree(initial, excludes=None)¶

Collect a Distribution and all direct and indirect dependencies of that distribution.

Parameters

initial (str) – Distribution name to collect from.
excludes (Optional[Iterable[str]]) – Distributions to exclude.

Return type

dict

Returns

A {name: distribution} mapping where distribution is the output of conda_support.distribution(name).

collect_dynamic_libs(name, dest='.', dependencies=True, excludes=None)¶

Collect DLLs for distribution name.

Parameters

name (str) – The distribution’s project-name.
dest (str) – Target destination, defaults to '.'.
dependencies (bool) – Recursively collect libs for dependent distributions (recommended).
excludes (Optional[Iterable[str]]) – Dependent distributions to skip, defaults to None.

Return type

List

Returns

List of DLLs in PyInstaller’s (source, dest) format.

This collects libraries only from Conda’s shared lib (Unix) or Library/bin (Windows) folders. To collect from inside a distribution’s installation use the regular PyInstaller.utils.hooks.collect_dynamic_libs().

The `hook(hook_api)` Function¶

In addition to, or instead of, setting global values, a hook may define a function hook(hook_api). A hook() function should only be needed if the hook needs to apply sophisticated logic or to make a complex search of the source machine.

The Analysis object calls the function and passes it a hook_api object which has the following immutable properties:

__name__:

The fully-qualified name of the module that caused the hook to be called, e.g., six.moves.tkinter.

__file__:

The absolute path of the module. If it is:

A standard (rather than namespace) package, this is the absolute path of this package’s directory.

A namespace (rather than standard) package, this is the abstract placeholder -.

A non-package module or C extension, this is the absolute path of the corresponding file.

__path__:

A list of the absolute paths of all directories comprising the module if it is a package, or None. Typically the list contains only the absolute path of the package’s directory.

co:

Code object compiled from the contents of __file__ (e.g., via the compile() builtin).

analysis:

The Analysis object that loads the hook.

The hook_api object also offers the following methods:

add_imports( *names ):: The names argument may be a single string or a list of strings giving the fully-qualified name(s) of modules to be imported. This has the same effect as adding the names to the hiddenimports global.
del_imports( *names ):: The names argument may be a single string or a list of strings, giving the fully-qualified name(s) of modules that are not to be included if they are imported only by the hooked module. This has the same effect as adding names to the excludedimports global.
add_datas( tuple_list ):: The tuple_list argument has the format used with the datas global variable. This call has the effect of adding items to that list.
add_binaries( tuple_list ):: The tuple_list argument has the format used with the binaries global variable. This call has the effect of adding items to that list.

The hook() function can add, remove or change included files using the above methods of hook_api. Or, it can simply set values in the four global variables, because these will be examined after hook() returns.

Hooks may access the user parameters, given in the hooksconfig argument in the spec file, by calling get_hook_config() inside a hook() function.

get_hook_config(hook_api, module_name, key)¶

Get user settings for hooks.

Parameters

module_name – The module/package for which the key setting belong to.
key – A key for the config.

Returns

The value for the config. None if not set.

The get_hook_config function will lookup settings in the Analysis.hooksconfig dict.

The hook settings can be added to .spec file in the form of:

a = Analysis(["my-app.py"],
    ...
    hooksconfig = {
        "gi": {
            "icons": ["Adwaita"],
            "themes": ["Adwaita"],
            "languages": ["en_GB", "zh_CN"],
        },
    },
    ...
)

The `pre_find_module_path( pfmp_api )` Method¶

You may write a hook with the special function pre_find_module_path( pfmp_api ). This method is called when the hooked module name is first seen by Analysis, before it has located the path to that module or package (hence the name “pre-find-module-path”).

Hooks of this type are only recognized if they are stored in a sub-folder named pre_find_module_path in a hooks folder, either in the distributed hooks folder or an --additional-hooks-dir folder. You may have normal hooks as well as hooks of this type for the same module. For example PyInstaller includes both a hooks/hook-distutils.py and also a hooks/pre_find_module_path/hook-distutils.py.

The pfmp_api object that is passed has the following immutable attribute:

module_name:: A string, the fully-qualified name of the hooked module.

The pfmp_api object has one mutable attribute, search_dirs. This is a list of strings that specify the absolute path, or paths, that will be searched for the hooked module. The paths in the list will be searched in sequence. The pre_find_module_path() function may replace or change the contents of pfmp_api.search_dirs.

Immediately after return from pre_find_module_path(), the contents of search_dirs will be used to find and analyze the module.

For an example of use, see the file hooks/pre_find_module_path/hook-distutils.py. It uses this method to redirect a search for distutils when PyInstaller is executing in a virtual environment.

The `pre_safe_import_module( psim_api )` Method¶

You may write a hook with the special function pre_safe_import_module( psim_api ). This method is called after the hooked module has been found, but before it and everything it recursively imports is added to the “graph” of imported modules. Use a pre-safe-import hook in the unusual case where:

The script imports package.dynamic-name
The package exists
however, no module dynamic-name exists at compile time (it will be defined somehow at run time)

You use this type of hook to make dynamically-generated names known to PyInstaller. PyInstaller will not try to locate the dynamic names, fail, and report them as missing. However, if there are normal hooks for these names, they will be called.

Hooks of this type are only recognized if they are stored in a sub-folder named pre_safe_import_module in a hooks folder, either in the distributed hooks folder or an --additional-hooks-dir folder. (See the distributed hooks/pre_safe_import_module folder for examples.)

You may have normal hooks as well as hooks of this type for the same module. For example the distributed system has both a hooks/hook-gi.repository.GLib.py and also a hooks/pre_safe_import_module/hook-gi.repository.GLib.py.

The psim_api object offers the following attributes, all of which are immutable (an attempt to change one raises an exception):

module_basename:: String, the unqualified name of the hooked module, for example text.
module_name:: String, the fully-qualified name of the hooked module, for example email.mime.text.
module_graph:: The module graph representing all imports processed so far.
parent_package:: If this module is a top-level module of its package, None. Otherwise, the graph node that represents the import of the top-level module.

The last two items, module_graph and parent_package, are related to the module-graph, the internal data structure used by PyInstaller to document all imports. Normally you do not need to know about the module-graph.

The psim_api object also offers the following methods:

add_runtime_module( fully_qualified_name ):

Use this method to add an imported module whose name may not appear in the source because it is dynamically defined at run-time. This is useful to make the module known to PyInstaller and avoid misleading warnings. A typical use applies the name from the psim_api:

psim_api.add_runtime_module( psim_api.module_name )

add_alias_module( real_module_name, alias_module_name ):

real_module_name is the fully-qualifed name of an existing module, one that has been or could be imported by name (it will be added to the graph if it has not already been imported). alias_module_name is a name that might be referenced in the source file but should be treated as if it were real_module_name. This method ensures that if PyInstaller processes an import of alias_module_name it will use real_module_name.

append_package_path( directory ):

The hook can use this method to add a package path to be searched by PyInstaller, typically an import path that the imported module would add dynamically to the path if the module was executed normally. directory is a string, a pathname to add to the __path__ attribute.

Understanding PyInstaller Hooks¶

How a Hook Is Loaded¶

Providing PyInstaller Hooks with your Package¶

Hook Global Variables¶

Useful Items in PyInstaller.compat¶

Useful Items in PyInstaller.utils.hooks¶

Support for Conda¶

The hook(hook_api) Function¶

The pre_find_module_path( pfmp_api ) Method¶

The pre_safe_import_module( psim_api ) Method¶

Useful Items in `PyInstaller.compat`¶

Useful Items in `PyInstaller.utils.hooks`¶

The `hook(hook_api)` Function¶

The `pre_find_module_path( pfmp_api )` Method¶

The `pre_safe_import_module( psim_api )` Method¶