An offline Python installation needs package files matching the target interpreter and platform, together with their dependencies. Prepare a small wheel collection, build a transfer bundle and install it in a fresh environment without network access. Check that the process can be repeated under the same target conditions.
The example uses Linux’s CPython 3.11 virtual environment and requests==2.32.5. This version is a fixed value for reproduction purposes and does not necessarily mean that it is the latest version. Business packages are selected based on organization-approved versions and security review criteria.
On this page
Match the collection environment and installation environment first.
wheel is a file that bundles Python packages into installable form. Pure Python packages can use the same files in multiple environments, but if native code is included, they must match the operating system, CPU, and Python ABI. ABI can be thought of as a convention by which compiled extension modules mesh with Python.
python3 --version
python3 -m pip --version
uname -m
cat /etc/os-release
python3 -m pip debug --verboseThis command checks on both the collection server and the destination server. The compatibility tag of pip debug --verbose is a clue to wheel selection. Compare files you received on Windows to avoid moving them to Linux, mixing x86_64 and ARM64, or importing files for different Python versions.
If possible, create a collection environment with the same OS, architecture, and Python version as the target. The target server must have Python, venv, or an equivalent virtual environment tool, pip, prepared in advance. OS packages such as Ubuntu’s python3-venv are not included in the wheel bundle created in this article.
Gather the files you need from an empty collection environment
Create a new working directory in the Internet-enabled collection environment. A separate virtual environment is used to prevent packages from existing development environments from being mixed. Check in the previous section that python3 is Python 3.11 in the example, and then run it.
mkdir offline-python
cd offline-python
python3 -m venv .collect
printf 'requests==2.32.5\n' > requirements.in
.collect/bin/python -m pip download \
--only-binary=:all: \
--dest wheelhouse \
-r requirements.inpip download downloads selected packages and dependencies. --only-binary=:all: restricts receiving only wheels instead of source compressed files. If a suitable wheel is not found, the collection step will fail, which reduces situations where unexpected compilation starts after entering a closed network. --no-deps, which subtracts dependencies, is not used here.
If you use a private package repository at work, specify the approved repository in the pip settings of the collection environment. Do not put URLs containing authentication tokens or personal pip configuration files in your import bundle. Even if you change the storage location, the condition that you must collect files that match the target environment is the same.
Install with the collected files and fix the version.
.collect/bin/python -m pip install \
--no-index --find-links=wheelhouse \
--only-binary=:all: \
-r requirements.in
.collect/bin/python -m pip check
.collect/bin/python -m pip freeze > requirements.txt
.collect/bin/python -m pip download \
--only-binary=:all: \
--dest wheelhouse \
-r requirements.txtAt first, only directly requested packages were listed in requirements.in. requirements.txt created after installation also contains the dependency versions selected in this environment. The final download step is to double-check whether the wheels you need in the list are in the bundle.
pip freeze records the current installation state and does not create a universal lock file that works across different OSs and all Python versions. If you run it in a development environment where several tools are already installed, unnecessary packages may be mixed in. This is why we first created an empty virtual environment in this article.
Imports the file list and checksum together.
sha256sum requirements.txt wheelhouse/*.whl > SHA256SUMS
tar -czf offline-python-bundle.tar.gz \
requirements.txt wheelhouse SHA256SUMSAlong with the bundle, the target OS·CPU·Python·pip version, collection date, and used package repository are recorded in the operation history. Checksum is used to check whether the file has changed during copying. The checksum in the same bundle does not guarantee the identity of the distributor or the safety of the file.
Compressed files are moved according to the organization’s import procedures and malware inspection standards. It is better not to copy the entire virtual environment directory .collect. Since the virtual environment is linked to the interpreter path and system libraries, it is difficult to guarantee that it will operate as is on other servers.
Install in a new virtual environment on a closed network.
On the target server, navigate to the directory containing the imported files. Before installing over an already running app environment, check first in the new directory and new virtual environment. The commands below assume that the compressed file is in the current directory.
mkdir offline-install-check
cd offline-install-check
tar -xzf ../offline-python-bundle.tar.gz
sha256sum -c SHA256SUMS
python3 -m venv .app
.app/bin/python -m pip install \
--no-index --find-links=wheelhouse \
--only-binary=:all: --no-cache-dir \
-r requirements.txt
.app/bin/python -m pip check
.app/bin/python -c 'import requests; print(requests.__version__)'--no-index prevents querying the package index, and --find-links specifies the local wheel location. Since index access is not blocked simply by specifying a local directory, use both options together. --no-cache-dir reduces the number of local caches passing verification by serving missing files instead.
The requirements in this example contain only a version specification. If the file contains a direct download URL or Git address, a separate external connection may be required. Check the list to be imported by reading it yourself. After importing a module, you must also run representative tasks for the actual app. pip check is a package dependency check and does not verify external shared libraries or entire business functions.
If installation fails, compare file types and target environment
| Error/Symptom | What to check |
|---|---|
No matching distribution found | Missing wheel in requested version, Python version/compatibility tag mismatch |
not a supported wheel on this platform | Check whether the OS·CPU·Python ABI matches the tag in the file name |
| Dependent package not found | Check whether only top-level packages are imported and whether requirements and wheelhouse are bundled together |
| Compiler/build tools required during installation | Make sure you have a source distribution or local project |
| Shared library loading fails after installation | Check execution conditions outside the wheel, such as OS libraries and drivers |
Packages that do not provide a wheel can be prepared with pip wheel in a build environment compatible with the target. At this time, you need to manage the compiler, headers, build dependencies, and even the resulting executable library. Just adding --no-build-isolation will not create the necessary tools.
When cross-collecting from other environments, review the --platform, --python-version, --implementation, and --abi options of pip download together. This option is a tool for specifying target compatibility and does not mean running the entire target OS. To check environmental markers and runtime conditions, it is clearer to collect and verify them in the same environment as the target.
Scope confirmed by networkless verification
At time of writing, requests 2.32.5 and its dependency wheel have been collected from a Python 3.11 container. I ran a new container that can only read that file as --network none, installed a new virtual environment, and checked the import and version output as pip check. The results are not based on verification of GPU packages or other OS combinations.
If you need to provide the OS package as internal storage, you can see Creating a Linux local repository. If you need to select a development environment, you can see venv·uv·conda selection. Once the import bundle is complete, check whether the new virtual environment installation is repeated under the same target conditions.
reference document
pip download: Dependency collection and target platform
pip install: local files and –no-index
