{"id":2188,"library":"pex","title":"PEX Packaging Toolchain","description":"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.","status":"active","version":"2.92.1","language":"en","source_language":"en","source_url":"https://github.com/pex-tool/pex","tags":["packaging","cli","deployment","virtualenv","reproducibility","build-system"],"install":[{"cmd":"pip install pex","lang":"bash","label":"Install PEX"}],"dependencies":[],"imports":[{"note":"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.","symbol":"PEXBuilder","correct":"from pex.pex_builder import PEXBuilder"}],"quickstart":{"code":"# Create a simple Python script\necho 'import sys; import requests; print(f\"Python: {sys.version.splitlines()[0]}\"); print(f\"Requests: {requests.__version__}\")' > hello_pex.py\n\n# Build a PEX file that includes 'requests' and executes 'hello_pex.py'\n# The --python-shebang ensures the PEX uses the system's python3 or specified path\npex requests --python-shebang /usr/bin/env python3 -o hello.pex -m hello_pex\n\n# Execute the PEX file\n./hello.pex","lang":"bash","description":"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."},"warnings":[{"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.","message":"PEX 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"PEX 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"PEX 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.","severity":"gotcha","affected_versions":"All versions (2.92.1 fixed a specific sdist caching bug)"},{"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.","message":"Versions 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.","severity":"breaking","affected_versions":"<2.91.8"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}