Handling Python deployments in environments cut off from the internet means developers must rethink how they manage dependencies. Standard installation commands that pull packages from public indexes fail on air-gapped or tightly controlled systems. Instead, teams need every required package and dependency on hand, verified, and ready for local installation.
Why Offline Packaging Matters
In isolated or secure setups, missing a single dependency or including a source archive that can't be built on the target system can stop deployment cold. Manually gathering packages takes time and often leads to mistakes, especially when checking each file's integrity. The Python Packaging User Guide points out that a "source distribution" is unbuilt and needs a build step when pip installs it. This can cause reliability problems if compilers or build tools aren't available on the target host. Wheels, on the other hand, are built distributions and usually install without a build process. This makes them much faster and more reliable for users. For offline deployment, it's best to pick artifacts that match the target interpreter, operating system, processor architecture, and Python ABI, rather than assuming every package can be built locally. Wheelhouse Packer automates this, lowering the risk of missing dependencies and making sure every package is ready for offline installation. Python Packaging User Guide
How Wheelhouse Packer Works
Wheelhouse Packer is a standalone Python script built with only the standard library. It downloads all listed dependencies, checks the resulting files, verifies their cryptographic hashes, and creates a manifest and installation scripts. The tool doesn't need any third-party packages, so it fits environments with strict software controls.
Installation and Basic Usage
To begin, download the script and save it as wheelhouse_packer_offline_install_bundles.py. You can see available options by running:
python wheelhouse_packer_offline_install_bundles.py --help
To package dependencies from a requirements file, use:
python wheelhouse_packer_offline_install_bundles.py -r requirements.txt -o ./offline-bundle
Or, specify packages directly:
python wheelhouse_packer_offline_install_bundles.py cryptography requests urllib3 -o ./offline-bundle
Targeting Specific Environments
If you need to build a bundle for a different platform or Python version, Wheelhouse Packer lets you set platform tags, Python versions, and ABI configurations. For example:
python wheelhouse_packer_offline_install_bundles.py -r requirements.txt -o ./offline-bundle --python-version 311 --platform manylinux2014_x86_64 --implementation cp
This makes sure the collected wheels fit the target environment, cutting down on installation failures from platform mismatches. The official wheel specification separates pure Python wheels, which work on any compatible interpreter, from platform wheels, which have compiled extensions and are tied to certain operating systems or architectures. Before moving a wheelhouse to an air-gapped system, record the target interpreter and platform details and check that all wheel tags match the deployment environment. Wheel specification
What the Output Contains
- wheels/: All downloaded package archives.
- manifest.json: An inventory of every file, including package version, archive type, and cryptographic hash.
- requirements.pinned.txt: A requirements file with strict SHA-256 hashes for each dependency.
- install.sh, install.bat, and install.py: Automated scripts for installing the packages on the target machine without network access.
How the Process Works
Wheelhouse Packer coordinates several standard library modules, such as hashlib, subprocess, json, and pathlib, to automate collecting and verifying offline bundles. It builds download commands using the host system's packaging tools and puts all artifacts in a dedicated output directory. Each file gets checked for its cryptographic hash, and the tool separates pre-built wheels from source archives. This matters because source distributions might need compilers or development headers that aren't on the target system. The Python Packaging User Guide notes that installing wheels is "substantially faster" for users than installing from source distributions, and that source distributions need a build step when pip installs them.
Automated Installation Scripts
To make deployment easier, the tool creates three installation scripts: install.sh for Unix-like systems, install.bat for Windows, and install.py as a cross-platform Python script. These scripts turn off remote package lookups, point to the local directory, and enforce hash checks. On the target machine, running python install.py installs all dependencies from the offline bundle. The official Python Packaging User Guide describes this offline installation pattern with the command python3 -m pip install --no-index --find-links=/local/dir/ requests, which blocks index access and tells pip to search the specified local location. Local archives can include ZIP files, wheels, or tar archives, and requirements files are recommended for declaring a project’s dependencies. pip installation guide
Technical Limitations and Considerations
- Host Tooling Dependency: The script needs package management tools accessible via sys.executable. If these are missing, the download process can't run.
- Cross-Platform Resolution: When targeting a different architecture, dependency resolution may fall short if conditional dependencies can't be resolved for the remote platform.
- Source Distributions: If a package doesn't have a pre-built wheel, the script collects the source archive and flags it in manifest.json. The target system must have the right build tools to install these packages. The Python Packaging User Guide notes that a source distribution is unbuilt and needs a build step when pip installs it, which may not work on all systems.
- Python Interpreter Requirement: The bundle doesn't include a Python interpreter. The target environment must already have a compatible Python runtime installed.
Security and Integrity
Hash-pinned requirements files are created to make sure every package installed matches the exact SHA-256 digest recorded during packaging. The official wheel specification requires that the hash algorithm in the RECORD file must be sha256 or better; md5 and sha1 are not allowed. During extraction, installers check the recorded hashes, and installation fails if files are missing from RECORD or have wrong hashes. This gives an integrity check inside each wheel. It's especially important in secure or regulated environments, where verifying dependency integrity is required.
Frequently Asked Questions
- Does Wheelhouse Packer require third-party packages? No, it uses only the Python standard library.
- Why are hash-pinned requirements important? They make sure only verified, untampered packages get installed on the target system, following best practices described by the Python Packaging Authority.
- What if a source archive is included? The tool flags source distributions in manifest.json. If the target machine doesn't have a C compiler or build tools, you need to swap the source archive for a compatible pre-built wheel before deployment. The Python Packaging User Guide recommends picking artifacts that fit the target interpreter and platform to avoid build failures.
For more details and access to the full toolkit, visit the official Wheelhouse Packer page on PyForge.
