Air-gapped Python: Setting up Python without a net(work)

The vast majority of modern software development revolves around one big assumption: that you always have a network connection. If you don’t, it’s typically because you’re on an airplane with no Wi-Fi, and that’s temporary.

But what about when you’re in an environment where there’s no connection by design? How do you, a Python developer, deal with working on a system that has either undependable network connectivity or none at all?

The good news is, you can make it work, provided you have two basic requirements in place. First, you must have another computer with network connectivity. Second, you must be able to copy files manually to and run software installs on the no-or-low-network machine. Then you can set up Python and pip install packages as needed.

The downside of the process are the steps involved (more than normal) and the loss of flexibility. You’ll have to know in advance what you need to install. Things may also get more complicated if you have dependencies that aren’t part of the Python ecosystem, like a C compiler.

But, if air-gapped Python is what you need, here’s how to get it.

Step 1: Gather the components

To start the process, figure out a list of what you’ll need to obtain for your Python projects. This breaks down to two basic categories:

1) Python itself

If you don’t have the Python runtime on the target system, or the proper edition for your use, you’ll need to obtain an installer for that version of Python. On Microsoft Windows or macOS, this doesn’t involve much more than downloading the installer executable.

On Linux, the process is far more complex and varies between package management systems. For instance, Ubuntu/Debian systems can use a utility, apt-offline, to obtain packages for offline installation.

2) Python packages you want to install

Python packages can be distributed as self-contained .whl files. Installing them is easy: pip install /path/to/file.whl.

It’s also not hard to download wheels as files using pip. The pip download <package_name> command will obtain the .whl file for the package in question and save it in the current working directory.

You can also use download to snag all the requirements needed for a package from a requirements.txt file: pip download -r <requirements>.

There are two important things to keep in mind about using pip download. First, Python packages can have dependencies, and you probably want the most proper list of the dependencies for the project(s) you want to port to the target system. It’s best to get that list from an actual installed copy of the packages:

1. Create a virtual environment.
2. Install everything you need into it.
3. Use pip freeze to dump the package list to a file. This file can then be used as your requirements.txt file to download everything.

Many packages depend on Python tooling like setuptools and wheel, so this is a convenient way to include those tools in the requirements list.

Important: With pip download, keep in mind that you should always run pip from the same version of Python you intend to use on the target machine. If, for instance, you’re using Python 3.12 on the air-gapped machine, you’ll need to run pip download using Python 3.12 on the networked machine. If you can’t do this, you can pass --python-version <version_number>. This flags pip download to specify the version of Python so you obtain wheels for that version.

If you want to download .whl files manually from PyPI, you can directly download installation files for any PyPI-hosted project from its PyPI page. Click on Download files in the left-hand Navigation column, and you’ll see a list of all the files available.

Note that you might not see a download that matches precisely your version of Python. This isn’t always a problem. Wheels files with an identifier in the name like py3-none-any are typically compatible with most any current version of Python. The Classifiers | Programming Language list in the bottom left-hand side of the PyPI project page typically lists the specific versions of Python you can use.

If you only see .tar.gz files instead of .whl files, that is a distribution of the original source code, which can also be installed with pip. Note that there may be build requirements involved for installing from source, so you’d need to also install on the target system any such requirements, like a C compiler. (More on this later.)

Step 2: Transport the files and set up the interpreter and apps

Once you’ve copied the files over, setting up the interpreter will (again) depend on the operating system you’re using. On Windows and macOS the process is as easy as running the installer executable. For Linux, each package manager will have its own behavior and syntax for installing from an offline package. You’ll need to consult your distribution’s package manager documentation for those details.

When you want to set up your Python application’s requirements, create a virtual environment for the app as you usually would, then run pip:

pip install <requirements> --no-index -f /path/to/wheels

Here, <requirements> is the file that contains your project’s requirements. --no-index forces pip to ignore checking PyPI for packages. The -f option lets you provide a path for pip to search for Python .whl files. This is where you provide the directory where you’ve copied those files.

if you’re doing an in-place editable install of the package, use this variant:

pip install -e . --no-index -f /path/to/wheels

This uses whatever requirements are in pyproject.toml for the project. Note, again, that if you haven’t copied all the needed requirements over, the installation will fail. This is another argument for obtaining the requirements list using pip freeze in a venv where the app is already installed.

Installing third-party Python package dependencies offline

The most complex installations involve third-party dependencies that aren’t packaged as Python wheels. For instance, if you’re using a Python package that has a C extension, and you’re not installing from a precompiled binary wheel, the install process will attempt to find a C compiler to build the extension.

To that end, you’ll also need to copy over and set up any of those third-party build dependencies. The bad news: It’s possible not all of those will be tracked explicitly in Python package manifests. In fact, most aren’t, since Python’s packaging system has no mechanism for doing this. Third-party Python distributions like Anaconda do have that power, but at the cost of having to use an entirely different Python distribution.

A common missing component for Python packages is a C compiler, typically for building CPython extensions from source. On Microsoft Windows, that C compiler is typically the Microsoft Visual C++ Compiler (MSVC), since CPython is compiled with it on Windows. You don’t need all of Visual Studio to use it, though; you can install a minimal, command-line-only version of MSVC, a package called the Visual Studio C++ Build Tools.

Unfortunately, creating an offline installation package for Visual Studio C++ Build Tools is a complex process. It involves making a “local layout” installation of the needed files—essentially, creating an install of Visual Studio on a networked machine with only the command-line components you need, then transferring that layout to the target machine and installing from there.