Welcome to pychub! This README is a quick overview of the project. It is meant to give you the fastest possible overview. For more details, see the very comprehensive USER_GUIDE.
pychub is a packaging tool that bundles your Python wheel and all of its
dependencies into a single, self-extracting .chub file.
It’s like a "wheel extension": it still uses your host Python interpreter, but comes with all dependencies and extras pre-downloaded, so installs are predictable, reproducible, and network-free.
To be clear, pychub does not compete with any other post-build packaging tools. Any of the various tools in this space might fit your needs better than any of the others. Each of these tools has overlap with the others, and each shines in their particular target areas. Likewise, pychub is most useful when you want a bundle that you can ship to any machine, regardless of the environment, and install the wheels and dependencies persistently.
A .chub file is only portable across environments if all bundled wheels are
universal. That means:
- Pure-Python wheels (
py3-none-any) - Platform-independent
manylinuxwheels - Universal2 wheels (for macOS)
If your package or its dependencies include compiled extensions
(e.g., numpy, Pillow, pydantic-core), the resulting .chub will only work on
the platform it was built for — and only with the matching Python version and
ABI.
In these cases, the .chub file is not cross-platform. In an upcoming
release, pychub will warn or fail on such builds unless explicitly overridden.
In practice, many popular packages include native extensions, so full cross-platform compatibility is rare unless your dependencies are pure Python.
While pychub has quite a few features, you can get started with just two commands in your shell, and you can see it demonstrate its simplest feature.
Build a .chub from your wheel:
pychub dist/mypackage-1.0.0-py3-none-any.whl
Run (extract/install) it anywhere with Python 3.9+:
python mypackage-1.0.0.chub
That’s it — no pip, no network, no surprises.
- Single-file distribution — ship a
.chubanywhere. - Network-free installs — dependencies are already inside the bundle.
- Environment agnostic — works with system Python, venv, or conda.
- Optional entrypoint — run your tool right after installation.
- Extras included — add configs, docs, or scripts if you want.
Use your favorite build system with a companion plugin:
See the pychub-build-plugins repo.
If you use another build system, please consider requesting, or even contributing, a plugin for it!
For a full walkthrough with CLI options, examples, comparison tables, and roadmap, see the USER_GUIDE.
Released under the MIT License.