Complete Guide to Offline Python Package Installation: Dependency Management and Environment Deployment

Fundamental Principles of Offline Package Installation

In software development, there is often a need to deploy Python applications in environments without internet connectivity. This scenario commonly occurs in production servers, security-sensitive environments, or network-restricted development settings. The core challenge of offline installation lies in properly handling package dependencies to ensure all necessary components can be successfully installed on the target machine.

Package Download and Dependency Management

For machines with internet access, the pip download command can be used to obtain packages and all their dependencies. This command recursively downloads all dependencies of specified packages, ensuring that offline installation won't fail due to missing dependencies. For example, to download the requests library and its dependencies:

pip download requests

For more complex projects, using a requirements.txt file to manage dependencies is recommended:

pip download -r requirements.txt -d ./wheelhouse

This approach automatically creates a wheelhouse directory, storing all downloaded package files for subsequent transfer and installation.

Manual Package Management Strategies

In some cases, manual management of package files may be necessary. This method is suitable for packages requiring specific versions or those not available on PyPI. Create a dedicated directory to store all package files:

mkdir /pypi
cd /pypi

Directory contents might include:

-rw-r--r-- 1 user staff 237954 Apr 19 11:31 Flask-WTF-0.6.tar.gz
-rw-r--r-- 1 user staff 389741 Feb 22 17:10 Jinja2-2.6.tar.gz
-rw-r--r-- 1 user staff 70305 Apr 11 00:28 MySQL-python-1.2.3.tar.gz

For custom packages or those not on PyPI, manual download and addition to this directory is required.

Development Environment Configuration

During development, the develop mode of setup.py can be used to install applications:

python setup.py develop --always-unzip --allow-hosts=None --find-links=/pypi

This approach allows running applications directly from the source code directory, facilitating development and debugging. For standard installation:

easy_install --always-unzip --allow-hosts=None --find-links=/pypi .

Both methods strictly limit dependency searches to the specified local directory and won't attempt downloads from the internet.

Importance of Virtual Environments

Using virtual environments for all installation operations is strongly recommended. Virtual environments isolate dependencies between different projects, preventing contamination of the global Python environment. Basic steps for creating and using virtual environments:

python -m venv myenv
source myenv/bin/activate

Performing all package installation operations within virtual environments ensures clear dependency management and environment reproducibility.

Cross-Machine Deployment Strategies

When source and target machines share the same architecture, the entire virtual environment can be packaged for transfer:

tar -zcf environment.tar.gz myenv/

Before transfer, the virtual environment needs to be made relocatable:

virtualenv --relocatable myenv

The target machine must have the same Python version installed, and any C extension dependencies (such as libpng, libjpeg, etc.) must be pre-installed.

Special Considerations for FreeBSD Systems

On FreeBSD systems using the pkg tool for package management, offline installation faces dependency resolution challenges. A typical installation process:

pkg add ./some_package.txz

May encounter dependency missing errors, requiring manual download and installation of all dependency packages. This process may require multiple iterations until all dependencies are satisfied.

Best Practices Summary

Successful offline installation requires a systematic approach: first completely download all dependencies in a networked environment, use requirements.txt files to explicitly record dependency relationships, manage project isolation through virtual environments, and thoroughly test the installation process before deployment. For complex projects, creating complete installation packages or container images is recommended to ensure deployment consistency and reliability.