iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
A PyInstaller hidden import is a Python module that the application needs but PyInstaller’s analysis does not detect in the source code. This often happens when code chooses a module at runtime, such as through a plugin name or a call to importlib.import_module(). If that module is absent from the frozen bundle, the application can fail when it tries to load it.
Dynamic imports do not automatically break, and they are not the only cause of an incomplete bundle. The right fix depends on whether the missing item is a Python module, an import search path, or a separate resource such as a data file or shared library.
What is a PyInstaller hidden import?
PyInstaller analyzes your application to find the modules it needs and include them in the bundle. A hidden import is a module that must be included even though it is not visible to that source analysis as an ordinary import. The PyInstaller command-line guide describes --hidden-import as a way to “Name an import not visible in the code of the script(s).” PyInstaller’s usage guide
Recommended Free Tools
For example, a direct statement such as import package.module makes the dependency apparent in the code. But an application might instead build a module name from configuration and pass it to importlib.import_module(), call __import__(), or select a plugin at runtime. When the target is chosen this way, PyInstaller may not be able to infer which module the program will need.
#1 Best Overall
If analysis misses a required module, the build can still complete, but the frozen application may fail when execution reaches the code that requests it. The precise outcome depends on the code and on any PyInstaller hooks that apply to the dependency.
Why can dynamic imports fail when ordinary imports work?
PyInstaller can usually find dependencies imported through standard, statically visible import statements. Its hook documentation says that “The majority of Python packages use normal methods of importing their dependencies, and PyInstaller locates all their files without difficulty.” PyInstaller’s hook documentation
A runtime-selected module is different: its name or selection may not be knowable from the source PyInstaller analyzes. A plugin loader, for instance, may choose among modules based on a configuration value. If the build analysis cannot identify the possible target, it may not collect it. That is why dynamic imports are a common hidden-import cause.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesHowever, it is not accurate to say that only dynamic imports break. Dynamic imports can work when PyInstaller or a hook can identify the needed modules, and other unusual import mechanisms or runtime changes can also make collection unreliable. Missing data files, shared libraries, or package metadata are separate problems; they are not hidden imports in the narrow sense.
How to choose the right fix
Start by identifying what the application cannot find. If it is a Python module, explicitly naming that module is usually the narrowest remedy. If the problem applies to a package more broadly, a hook or collection option may be more suitable. If the module is present but outside the build’s import search path, adjust that path instead.
| Remedy | Scope | Use it when |
|---|---|---|
--hidden-import |
One named module; the option can be repeated. | You know the specific module the frozen application needs. |
Package hook with hiddenimports |
Package-specific rules applied during analysis. | You want a reusable way to declare indirect imports associated with a package. |
--collect-submodules |
Submodules of a named package. | The application needs a known group of modules within a package. |
--collect-all |
Submodules, data files, and binaries for a package. | The application needs that broader set of package contents, not just one module. |
--paths DIR |
An additional directory in the analysis import search path. | The module exists but is not discoverable from the build environment’s current search path. |
These options are documented in PyInstaller’s usage guide. Choose the narrowest option that matches the missing item: broad collection can include modules or resources the application does not need.
How to declare a hidden import
Add a module on the command line
Pass the exact module name to PyInstaller with --hidden-import. For example, if the missing target is package.module:
pyinstaller --hidden-import=package.module your_script.pyUse the actual entry-point script and module name from your project. To declare more than one known module, repeat the option:
pyinstaller --hidden-import=package.module --hidden-import=another.module your_script.pyDeclare package-specific imports in a hook
A hook can tell PyInstaller which indirect imports belong with a package by setting a hiddenimports list. The documented pattern is:
hiddenimports = ["package.module"]PyInstaller applies a hook when analysis encounters the module the hook covers. This is useful when the package has known indirect imports that should be handled consistently. The official hook documentation illustrates the approach with xml.dom.minidom, reached through indirect registration. Understanding PyInstaller Hooks
Collect a package’s modules or broader contents
Use --collect-submodules package when the application needs the package’s submodules as a group. Use --collect-all package only when it also needs the package’s data files and binaries. These options are broader than naming one hidden import.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Correct an import search-path issue
If analysis cannot find a module because its directory is not on the search path, use --paths DIR to add the relevant directory. This makes code discoverable during analysis; it is different from explicitly declaring a module that source analysis cannot see.
When a hidden import is the wrong diagnosis
A missing-module error can point to a hidden import, but not every frozen-app failure is a Python import problem. Check what the application is trying to load before changing collection settings.
- Python module: If a named module is absent when the application imports it, consider
--hidden-import, a hook, or an appropriate submodule collection option. - Module exists but analysis cannot find it: Check whether its directory is available in the build environment;
--paths DIRmay address the search path. - Data file: A file the program reads at runtime requires data-file collection, not a hidden import.
- Shared library or package metadata: These have their own collection needs; adding a Python module name does not collect them.
PyInstaller hooks can manage data files, binaries, and metadata as well as hidden imports. The correct remedy therefore depends on the missing item, not merely on the fact that the frozen program failed.
What to check when the cause is unclear
The general mechanics do not identify why a specific application failed. To narrow it down, inspect the dependency name, the code that loads it, the PyInstaller build warnings or logs, and the Python and PyInstaller versions used for the build. Those details help distinguish an uncollected module from a path, data, binary, or metadata problem. Whether a particular dependency already has a suitable hook also depends on that package and build setup.
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
