Provide a similar feature to standalone mode

Oct 13, 2025 by wbrum.org 136 views

Bug Description

According to the Nuitka Release 26 blog post, the package mode was introduced to automatically include all sub-modules of a package without requiring manual specification with --include-package. However, this feature does not seem to work as expected when it comes to third-party packages from PyPI that a package depends on.

Testing the Package Mode

To test this feature, I used the following command:

poetry run nuitka --verbose --mode=package mypackage

However, the compilation did not include third-party packages from PyPI that my package depends on. The --verbose output confirmed that these third-party packages were not discovered. As a result, I still need to manually include third-party packages using --include-package.

Questions

Is this the expected behavior? Or am I misunderstanding the feature?
If this is out of scope for package mode, could you suggest how to compile a single .so file that includes all third-party dependencies, including sub-dependencies?

For example:

mypackage --> third-party packages --> sub-third-party packages

I noticed that standalone mode has a --follow-imports option. Is there any plan to support a similar feature in package mode?

Related Issue

https://github.com/Nuitka/Nuitka/issues/1943

Understanding the Issue

The issue here is that the package mode does not automatically include third-party dependencies, which are essential for the proper functioning of the package. This means that users need to manually include these dependencies using --include-package, which can be time-consuming and error-prone.

Possible Solutions

Modify the package mode to include third-party dependencies: This would involve modifying the package mode to automatically include third-party dependencies, similar to how standalone mode works with --follow-imports.
Provide a similar feature to standalone mode: This would involve providing a similar feature to standalone mode, such as --follow-imports, that can be used in package mode to automatically include third-party dependencies.
Improve the documentation: This would involve improving the documentation to clearly explain how to use the package mode and how to include third-party dependencies.

Conclusion

The package mode in Nuitka does not automatically include third-party dependencies, which can make it difficult to use. To resolve this issue, we need to either modify the package mode to include third-party dependencies or provide a similar feature to standalone mode. Improving the documentation can also help users understand how to use the package mode and include third-party dependencies.

Future Work

To address this issue, we need to:

Modify the package mode to include third-party dependencies: This would involve modifying the package mode to automatically include third-party dependencies, similar to how standalone mode works with --follow-imports.
Provide a similar feature to standalone mode: This would involve providing a similar feature to standalone mode, such as --follow-imports, that can be used in package mode to automatically include third-party dependencies.
Improve the documentation: This would involve improving the documentation to clearly explain how to use the package mode and how to include third-party dependencies.

Related Work

https://github.com/Nuitka/Nuitka/issues/1943

References

Nuitka Release 26 blog post

Future Research Directions

Investigate the feasibility of modifying the package mode to include third-party dependencies: This would involve investigating the feasibility of modifying the package mode to automatically include third-party dependencies.
Explore the possibility of providing a similar feature to standalone mode: This would involve exploring the possibility of providing a similar feature to standalone mode, such as --follow-imports, that can be used in package mode to automatically include third-party dependencies.
Improve the documentation to clearly explain how to use the package mode and include third-party dependencies: This would involve improving the documentation to clearly explain how to use the package mode and include third-party dependencies.
Package Mode Does Not Automatically Include Third-Party Dependencies ================================================================================

Q&A

Q: What is the package mode in Nuitka? A: The package mode in Nuitka is a feature that automatically includes all sub-modules of a package without requiring manual specification with --include-package.

Q: Does the package mode include third-party dependencies? A: No, the package mode does not automatically include third-party dependencies. This means that users need to manually include these dependencies using --include-package.

Q: Why is this a problem? A: This is a problem because third-party dependencies are essential for the proper functioning of the package. Without them, the package may not work as expected.

Q: Is this the expected behavior? A: No, this is not the expected behavior. The package mode is supposed to automatically include all sub-modules of a package, including third-party dependencies.

Q: Can I use the standalone mode instead? A: Yes, you can use the standalone mode instead. The standalone mode has a --follow-imports option that can be used to automatically include third-party dependencies.

Q: Is there any plan to support a similar feature in package mode? A: Yes, there is a plan to support a similar feature in package mode. However, this feature is still in development and not yet available.

Q: How can I include third-party dependencies in package mode? A: You can include third-party dependencies in package mode by using the --include-package option. This option allows you to specify the packages that you want to include.

Q: Can I use a wildcard to include all third-party dependencies? A: No, you cannot use a wildcard to include all third-party dependencies. You need to specify each package individually using the --include-package option.

Q: Is there any documentation available on how to use the package mode? A: Yes, there is documentation available on how to use the package mode. You can find it in the Nuitka documentation.

Q: Can I contribute to the development of Nuitka? A: Yes, you can contribute to the development of Nuitka. You can submit bug reports, feature requests, and patches to the Nuitka project.

Related Issues

https://github.com/Nuitka/Nuitka/issues/1943

References

Nuitka Release 26 blog post

Future Research Directions

Investigate the feasibility of modifying the package mode to include third-party dependencies: This would involve investigating the feasibility of modifying the package mode to automatically include third-party dependencies.
Explore the possibility of providing a similar feature to standalone mode: This would involve exploring the possibility of providing a similar feature to standalone mode, such as --follow-imports, that can be used in package mode to automatically include third-party dependencies.
Improve the documentation to clearly explain how to use the package mode and include third-party dependencies: This would involve improving the documentation to clearly explain how to use the package mode and include third-party dependencies.