The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →PyInstaller’s Analysis phase can usually find modules named in ordinary import statements. A hidden import is a module the application needs but that analysis cannot see in the source; if the program asks for it at runtime, the frozen application may fail because the module was not bundled. Specify a known module with --hidden-import, use a package hook, or collect a broader set of submodules when the package requires it.
What PyInstaller means by a hidden import
PyInstaller analyzes your program to identify Python modules to include in the bundle. Its command-line documentation describes --hidden-import as a way to “Name an import not visible in the code of the script(s).” The option can be used more than once. PyInstaller: Using PyInstaller
As an Amazon Associate I earn from qualifying purchases.
The word “hidden” describes what the analysis can see, not a special kind of Python module. If your application needs a module but PyInstaller cannot identify it from the analyzed code or applicable hooks, you may need to tell the build to include it.
Why runtime-selected imports can go missing
An ordinary statement such as import package.module gives analysis a visible reference to follow. A program can instead choose a module at runtime—for example, by assembling its name from configuration and passing that name to importlib.import_module, using __import__, or selecting a plugin. The eventual target may not appear as a literal import in the analyzed source, so PyInstaller may not know to bundle it. The exact outcome depends on the code and any relevant hooks.
#1 Best Overall
That is why dynamic imports are a common cause of missing modules in frozen applications, but it is not accurate to say that only dynamic imports break. PyInstaller notes that most packages use normal import methods and are located without difficulty, while unusual import mechanisms or runtime changes can make collection unreliable. A missing data file, shared library, or package metadata is a different problem from a hidden Python-module import. PyInstaller: Understanding PyInstaller Hooks
Choose a fix that matches what is missing
| Remedy | Use it when | Scope |
|---|---|---|
--hidden-import=package.module |
You know the specific Python module the application needs, but analysis does not find it. | One named module; repeat the option for additional modules. |
Package hook with hiddenimports |
A package has import behavior that needs a reusable, package-specific declaration. | Modules declared by the hook when Analysis encounters the hooked package. |
--collect-submodules package |
The application needs a known package’s submodules rather than just one target. | Submodules of the named package. |
--collect-all package |
The application needs a broader package collection, including non-code resources. | Submodules, data files, and binaries for the named package. |
--paths DIR |
The module exists in the build environment but its directory is not on the analysis search path. | Adds a directory to the import search path; it does not declare a hidden import. |
The command-line options and their collection scopes are documented in PyInstaller: Using PyInstaller. Hook behavior, including hidden imports and collection of other resources, is described in PyInstaller: Understanding PyInstaller Hooks.
How to add a hidden import
Declare one known module in the build command
Add the exact importable module name to the PyInstaller command:
pyinstaller --hidden-import=package.module your_script.pyReplace package.module with the module your application actually requests. Add another --hidden-import option for each additional known module. This is the narrowest fix when the missing target is clear.
Put package-specific knowledge in a hook
A hook can declare hidden imports in a hiddenimports list, for example:
hiddenimports = ["package.module"]PyInstaller applies a hook when Analysis encounters the package it is associated with. This is useful when the package’s indirect imports should be handled consistently in builds that use the hook. The official hook documentation illustrates this pattern with an indirectly registered module. PyInstaller: Understanding PyInstaller Hooks
Collect a package’s wider contents only when needed
Use --collect-submodules package when the application needs a package’s submodules. Use --collect-all package only if it also needs that package’s data files and binaries. These broader options can include more than a single hidden import, so match the collection scope to the dependency rather than expanding it by default. PyInstaller: Using PyInstaller
When a hidden import is not the right fix
- The module is not discoverable during the build: Check whether it is installed in the build environment and whether its directory is searched.
--paths DIRadds an import search directory; it addresses analysis discoverability rather than a runtime-selected import target. - The failure names a file or package resource: Investigate data-file collection, not just Python imports.
- The failure names a shared library: Check binary collection and the dependency’s hook behavior.
- The failure involves package metadata: Use the relevant metadata collection mechanism rather than assuming a hidden module is missing.
PyInstaller hooks can manage data files, binaries, and package metadata as well as hidden imports. These resource-collection issues are related to bundling but are distinct from a Python module that analysis cannot see. PyInstaller: Understanding PyInstaller Hooks
Diagnose the failed build before widening collection
Start with the runtime error and build output. A missing-module error points toward an import or analysis-search issue; a missing file, shared library, or metadata lookup points toward a different collection requirement. Then identify the exact module or resource the application requests and choose the narrowest matching remedy. The official documentation explains the general mechanics, but identifying why a particular build fails depends on its dependency, Python and PyInstaller versions, build warnings or logs, and import code.
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.
