What are .pex files?

tl;dr

PEX files are self-contained executable Python virtual environments. More specifically, they are carefully constructed zip files with a #!/usr/bin/env python and special __main__.py that allows you to interact with the PEX runtime. For more information about zip applications, see PEP 441.

To get started building your first pex files, go straight to Building .pex files.

Why .pex files?

Files with the .pex extension – “PEX files” or “.pex files” – are self-contained executable Python virtual environments. PEX files make it easy to deploy Python applications: the deployment process becomes simply scp.

Single PEX files can support multiple platforms and python interpreters, making them an attractive option to distribute applications such as command line tools. For example, this feature allows the convenient use of the same PEX file on both OS X laptops and production Linux AMIs.

How do .pex files work?

PEX files rely on a feature in the Python importer that considers the presence of a __main__.py within the module as a signal to treat that module as an executable. For example, python -m my_module or python my_module will execute my_module/__main__.py if it exists.

Because of the flexibility of the Python import subsystem, python -m my_module works regardless if my_module is on disk or within a zip file. Adding #!/usr/bin/env python to the top of a .zip file containing a __main__.py and marking it executable will turn it into an executable Python program. pex takes advantage of this feature in order to build executable .pex files. This is described more thoroughly in PEP 441.