pex

library2.101.1pypypi✓ verified 24d ago

PEX (Python EXecutable) is a powerful Python packaging tool that creates self-contained Python environments, known as PEX files. These files bundle Python code, dependencies, and optionally a Python interpreter into a single executable, making applications portable and ensuring reproducible builds without needing `pip` or virtual environments on the target system. It simplifies deployment by providing a single artifact. The current version is 2.92.1, and it maintains a rapid release cadence with frequent bug fixes and feature enhancements.

devops

pip install pex

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PEX

pex

devopspythonv2.101.1

Install

3.0s avg

Import

595ms

Disk

37MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.101.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.620s · 42.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.0s · import 0.570s · 43MB

37MB installed

● package 37MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PEXBuilder

✓ from pex.pex_builder import PEXBuilder

PEX is primarily a command-line tool. The PEXBuilder API is typically used for integrating PEX file creation into larger build systems rather than general application development.

This quickstart demonstrates how to create a PEX file containing a simple Python script and the `requests` library. The `pex` command builds a self-contained executable that can then be run directly.

# Create a simple Python script echo 'import sys; import requests; print(f"Python: {sys.version.splitlines()[0]}"); print(f"Requests: {requests.__version__}")' > hello_pex.py # Build a PEX file that includes 'requests' and executes 'hello_pex.py' # The --python-shebang ensures the PEX uses the system's python3 or specified path pex requests --python-shebang /usr/bin/env python3 -o hello.pex -m hello_pex # Execute the PEX file ./hello.pex

pex --version

Debug

Known issues

gotchaPEX has explicit Python version compatibility requirements (e.g., `!=3.0.*, !=3.1.*, ..., <3.16, >=2.7`). Always verify the `requires_python` specification for the PEX version you are using. Attempting to build or run a PEX with an incompatible Python interpreter can lead to failures.

fix

Ensure your build environment and target runtime Python interpreters align with PEX's `requires_python` metadata. Use `--python` or `--python-shebang` arguments to explicitly control the interpreter used by the PEX.

affects: All versions

gotchaPEX is predominantly a command-line interface tool (`pex ...` or `python -m pex ...`). While a programmatic API (`pex.pex_builder.PEXBuilder`) exists, it is generally intended for complex build system integrations, not typical application-level programmatic use. Most user interactions should be via the CLI.

fix

For most use cases, leverage the powerful command-line interface. Refer to the official documentation for advanced CLI options and examples before attempting programmatic integration.

affects: All versions

gotchaPEX extensively uses a local cache (defaulting to `~/.pex`). Issues with stale or corrupted cache entries can lead to unexpected build failures or using outdated dependencies. Recent versions have addressed specific caching bugs.

fix

If encountering inexplicable build issues or dependency problems, try clearing the PEX cache by removing the `~/.pex` directory. Use `--no-pypi` or `--no-cache` for isolated builds, though this impacts performance.

affects: All versions (2.92.1 fixed a specific sdist caching bug)

breakingVersions prior to 2.91.8 had a bug where `--pylock` could fail when the lock file specified local project dependencies using relative paths. This could lead to build failures or incorrect dependency resolution.

fix

Upgrade to PEX version 2.91.8 or newer to correctly handle lock files containing relative paths for local project dependencies. If unable to upgrade, ensure all local project dependencies in your lock file use absolute paths.

affects: <2.91.8

Errors

Common errors & fixes

OSError: [Errno 13] Permission denied: '/home/.pex'

PEX attempts to create a cache directory, by default in `~/.pex`, but the current user lacks write permissions to this location.

fix

Set the `PEX_ROOT` environment variable to a writable directory before running pex, or use the `--pex-root` argument. Example: `export PEX_ROOT=/tmp/my_pex_root` or `pex --pex-root /tmp/my_pex_root ...`.

ModuleNotFoundError: No module named 'pex.bin'

This error typically indicates an issue with the pex installation itself or its environment, particularly when pex is invoked by another tool like Pants, leading to its internal modules not being found.

fix

Ensure `pex` is properly installed and its version is compatible with any integrating build systems. Upgrading `pex` or the build system (e.g., Pants) is often the solution. Using `--pex-verbosity=9` can provide more diagnostic information.

pex.pex_builder.InvalidExecutableSpecification: Could not find script 'mainscript.py' in any distribution within PEX!

PEX cannot find the specified entry point script or module within the packaged distributions, often due to an incorrect path in the `pex` command or a misconfigured `setup.py`.

fix

Double-check the entry point specified with `-c` (for console script) or `-e` (for module entry point) to ensure it correctly references an existing script or module within your project's `setup.py` or the provided source code.

Could not satisfy all requirements for <package> (from: <another_package>)

PEX's dependency resolver encountered a conflict or could not find a compatible set of versions for transitive dependencies, or multiple direct requirements for the same package were specified with conflicting constraints.

fix

Review your project's `requirements.txt` or direct dependency declarations for conflicting version constraints. You might need to explicitly specify compatible versions for the problematic packages or allow PEX to perform full dependency resolution if it was given pre-built artifacts without proper metadata.

Upgrade

Version history

2.101.1latest on PyPI · released Aug 28, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/pex-tool/pex ↗

packagehttps://pypi.org/project/pex/ ↗

homepagehttps://pex.readthedocs.io ↗

docshttps://docs.pex-tool.org/ ↗

changeloghttps://github.com/pex-tool/pex/blob/v2.95.2/CHANGES.md ↗