{"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":"python","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,"search_vec":"'2.92.1':68 'applic':40 'artifact':63 'bug':78 'build':45,89 'build-system':88 'bundl':26 'cadenc':75 'cli':84 'code':28 'contain':17 'creat':14 'current':65 'depend':29 'deploy':58,85 'enhanc':82 'ensur':43 'environ':19,51 'execut':6,38 'featur':81 'file':23,25 'fix':79 'frequent':77 'interpret':34 'known':20 'maintain':71 'make':39 'need':47 'option':31 'packag':2,11,83 'pex':1,4,22 'pip':48 'portabl':41 'power':9 'provid':60 'python':5,10,18,27,33 'rapid':73 'releas':74 'reproduc':44,87 'self':16 'self-contain':15 'simplifi':57 'singl':37,62 'system':55,90 'target':54 'tool':12 'toolchain':3 'version':66 'virtual':50 'virtualenv':86 'without':46","created_at":"2026-04-09T18:47:16.787048+00:00","updated_at":"2026-04-16T17:58:58.799050+00:00","problems":[{"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 ...`.","cause":"PEX attempts to create a cache directory, by default in `~/.pex`, but the current user lacks write permissions to this location.","error":"OSError: [Errno 13] Permission denied: '/home/.pex'"},{"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.","cause":"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.","error":"ModuleNotFoundError: No module named 'pex.bin'"},{"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.","cause":"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`.","error":"pex.pex_builder.InvalidExecutableSpecification: Could not find script 'mainscript.py' in any distribution within PEX!"},{"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.","cause":"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.","error":"Could not satisfy all requirements for <package> (from: <another_package>)"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.101.1","cli_name":"pex","cli_version":"2.95.0","type":"library","homepage":"https://pex.readthedocs.io","github":"https://github.com/pex-tool/pex","docs":"https://docs.pex-tool.org/","changelog":"https://github.com/pex-tool/pex/blob/v2.95.2/CHANGES.md","pypi":"https://pypi.org/project/pex/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}