The PEX packaging toolchain.
pex is a library for generating .pex (Python EXecutable) files which are executable Python environments in the spirit of virtualenvs. pex is an expansion upon the ideas outlined in PEP 441 and makes the deployment of Python applications as simple as cp. pex files may even include multiple platform-specific Python distributions, meaning that a single pex file can be portable across Linux and OS X.
Still unsure about what pex does or how it works? Watch this quick lightning talk: WTF is PEX?.
pex is licensed under the Apache2 license.
To install pex, simply
$ pip install pex
You can also build pex in a git clone using tox:
$ tox -e package $ cp dist/pex ~/bin
This builds a pex binary in dist/pex that can be copied onto your $PATH. The advantage to this approach is that it keeps your Python environment as empty as possible and is more in-line with what pex does philosophically.
Launch an interpreter with requests, flask and psutil in the environment:
$ pex requests flask 'psutil>2,<3'
Or instead freeze your current virtualenv via requirements.txt and execute it anywhere:
$ pex -r <(pip freeze) -o my_virtualenv.pex $ deactivate $ ./my_virtualenv.pex
Run webserver.py in an environment containing flask as a quick way to experiment:
$ pex flask -- webserver.py
Launch Sphinx in an ephemeral pex environment using the Sphinx entry point sphinx:main:
$ pex sphinx -e sphinx:main -- --help
Build a standalone pex binary into pex.pex using the pex console_scripts entry point:
$ pex pex -c pex -o pex.pex
You can also build pex files that use a specific interpreter type:
$ pex pex -c pex --python=pypy -o pypy-pex.pex
Most pex options compose well with one another, so the above commands can be mixed and matched. For a full list of options, just type pex --help.
Integrating pex into your workflow
If you use tox (and you should!), a simple way to integrate pex into your workflow is to add a packaging test environment to your tox.ini:
[testenv:package] deps = pex commands = pex . -o dist/app.pex
Then tox -e package will produce a relocateable copy of your application that you can copy to staging or production environments.
More documentation about Pex, building .pex files, and how .pex files work is available at https://pex.readthedocs.io.
Pex uses tox for test and development automation. To run the test suite, just invoke tox:
If you don’t have tox, you can generate a pex of tox:
$ pex tox -c tox -o ~/bin/tox
Tox provides many useful commands and options, explained at https://testrun.org/tox/en/latest/. Below, we provide some of the most commonly used commands used when working on Pex, but the docs are worth acquainting yourself with to better understand how Tox works and how to do more advanced commmands.
To run a specific environment, identify the name of the environment you’d like to invoke by running tox --listenvs-all, then invoke like this:
$ tox -e style
All of our tox test environments allow passthrough arguments, which can be helpful to run specific tests:
$ tox -e py37-integration -- -k test_reproducible_build
To run Pex from source, rather than through what is on your PATH, invoke via Python:
$ python -m pex
To contribute, follow these instructions: http://pantsbuild.org/howto_contribute.html
This is a hotfix release for the bug detailed in #756 that was introduced by #752 in python 3.7 interpreters.
We now support reproducible builds when creating a pex via pex -o foo.pex, meaning that if you were to run the command again with the same inputs, the two generated pexes would be byte-for-byte identical. To enable reproducible builds when building a pex, use the flags –no-use-system-time –no-compile, which will use a deterministic timestamp and not include .pyc files in the Pex.
In Pex 1.7.0, we will default to reproducible builds.
- add delayed pkg_resources import fix from #713, with an integration test (#730) PR #730
- Fix reproducible builds sdist test by properly requiring building the wheel (#727) PR #727
- Fix reproducible build test improperly using the -c flag and add a new test for -c flag (#725) PR #725
- Fix PexInfo requirements using a non-deterministic data structure (#723) PR #723
- Add new –no-use-system-time flag to use a deterministic timestamp in built PEX (#722) PR #722
- Add timeout when using requests. (#726) PR #726
- Refactor reproducible build tests to assert that the original pex command succeeded (#724) PR #724
- Introduce new –no-compile flag to not include .pyc in built pex due to its non-determinism (#718) PR #718
- Document how Pex developers can run specific tests and run Pex from source (#720) PR #720
- Remove unused bdist_pex.py helper function (#719) PR #719
- Add failing acceptance tests for reproducible Pex builds (#717) PR #717
- Make a copy of globals() before updating it. (#715) PR #715
- Make sure PexInfo is isolated from os.environ. (#711) PR #711
- Fix import sorting. (#712) PR #712
- When iterating over Zipfiles, always use the Unix file separator to fix a Windows issue (#638) PR #638
- Fix pex file looses the executable permissions of binary files (#703) PR #703
This is the first release including only a single PEX pex, which supports execution under all interpreters pex supports.
This release fixes long-broken resolution of abi3 wheels.
- Use all compatible versions when calculating tags. (#692) PR #692
This release un-breaks lambdex.
This release changes the behavior of the --interpreter-constraint option. Previously, interpreter constraints were ANDed, which made it impossible to express constraints like ‘>=2.7,<3’ OR ‘>=3.6,<4’; ie: either python 2.7 or else any python 3 release at or above 3.6. Now interpreter constraints are ORed, which is likely a breaking change if you have scripts that pass multiple interpreter constraints. To transition, use the native , AND operator in your constraint expression, as used in the example above.
- Make tox -evendor idempotent. (#651) PR #651
- Fix invalid regex and escape sequences causing DeprecationWarning (#646) PR #646
- Follow PEP 425 suggestions on distribution preference. (#640) PR #640
- Setup interpreter extras in InstallerBase. (#635) PR #635
- Ensure bootstrap demotion is complete. (#634) PR #634
This release brings an exit code fix for pexes run via entrypoint as well as a fix for finding scripts when building pexes from wheels with dashes in their distribution name.
This release brings a fix to handle top-level requirements with environment markers, fully completing environment marker support.
- Filter top-level requirements against env markers. (#592) PR #592
This release fixes pexes such that they fully support environment markers, the canonical use case being a python 2/3 pex that needs to conditionally load one or more python 2 backport libs when running under a python 2 interpreter only.
- Revert “Revert “Support environment markers during pex activation. (#582)”” PR #582
This is a hotfix release for 1.4.8 that fixes a regression in interpreter setup that could lead to resolved distributions failing to build or install.
This release adds support for -c and -m pexfile runtime options that emulate the behavior of the same arguments to python as well a fix for handling the non-standard platform reported by setuptools for Apple system interpreters in addition to several other bug fixes.
- Fix PEXBuilder.clone. (#575) PR #575
- Fix PEXEnvironment platform determination. (#568) PR #568
- Apply more pinning to jupyter in IT. (#573) PR #573
- Minimize interpreter bootstrapping in tests. (#571) PR #571
- Introduce 3.7 to CI and release. (#567) PR #567
- Add OSX shards. (#565) PR #565
- Add support for -m and -c in interpreter mode. (#563) PR #563
- Ignore concurrent-rename failures. (#558) PR #558
- Fixup test_jupyter_appnope_env_markers. (#562) PR #562
This is a hotfix release for a regression in setuptools compatibility introduced by #542.
- Fixup PEX.demote_bootstrap: fully unimport. (#554) PR #554
This release opens up setuptools support for more modern versions that support breaking changes in setup used in the wild.
- Fix for super() usage on “old style class” ZipFile (#546) PR #546
- Cleanup bootstrap dependencies before handoff. (#542) PR #542
- Support -c for plat spec dists in multiplat pexes. (#545) PR #545
- Support - when running as an interpreter. (#543) PR #543
- Expand the range of supported setuptools. (#541) PR #541
- Preserve perms of files copied to pex chroots. (#540) PR #540
- Add more badges to README. (#535) PR #535
- Fixup CHANGES PR links for 1.4.5.
This release adds support for validating pex entrypoints at build time in addition to several bugfixes.
- Fix PEX environment setup. (#531) #531
- Fix installers to be insensitive to extras iteration order. (#532) #532
- Validate entry point at build time (#521) #521
- Fix pex extraction perms. (#528) #528
- Simplify .travis.yml. (#524) #524
- Fix PythonInterpreter caching and ergonomics. (#518) #518
- Add missing git dep. (#519) #519
- Introduce a controlled env for pex testing. (#517) #517
- Bump wheel version to latest. (#515) #515
- Invoke test runner at a more granular level for pypy shard. (#513) #513
This release adds support for including sources and resources directly in a produced pex - without the need to use pants.
- Add resource / source bundling to pex cli (#507) #507
Another bugfix release for the 1.4.x series.
This release repairs a tag matching regression for .egg dists that inadvertently went out in 1.4.1.
- Improve tag generation for EggPackage. (#493) #493
A bugfix release for 1.4.x.
This release includes full Manylinux support, improvements to wheel resolution (including first class platform/abi tag targeting) and a handful of other improvements and bugfixes. Enjoy!
Special thanks to Dan Blanchard (@dan-blanchard) for seeding the initial PR for Manylinux support and wheel resolution improvements.
- Complete manylinux support in pex. (#480) #480
- Add manylinux wheel support and fix a few bugs along the way (#316) #316
- Skip failing tests on pypy shard. (#478) #478
- Bump travis image to Trusty. (#476) #476
- Mock PATH for problematic interpreter selection test in CI (#474) #474
- Skip two failing integration tests. (#472) #472
- Better error handling for missing setuptools. (#471) #471
- Add tracebacks to IntegResults. (#469) #469
- Fix failing tests in master (#466) #466
- Repair isort-check failure in master. (#465) #465
- Repair style issues in master. (#464) #464
- Fixup PATH handling in travis.yml. (#462) #462
- Add blacklist handling for skipping requirements in pex resolver #457 #457
This is a bugfix release for a regression that inadvertently went out in 1.3.0.
- inherit_path allows ‘prefer’, ‘fallback’, ‘false’ (#444) #444
- Change PEX re-exec variable from ENV to os.environ (#441) #441
- Bugfix for entry point targeting + integration test (#435) #435
- Add interpreter constraints option and use constraints to search for compatible interpreters at exec time (#427) #427
- Create –pex-path argument for pex cli and load pex path into pex-info metadata (#417) #417
- Allow passing a preamble file to the CLI (#400) #400
- Add first-class support for multi-interpreter and multi-platform pex construction. (#394) #394
- Fix for Ambiguous Resolvable bug in transitive dependency resolution (#367) #367
This release follows-up on 1.2.0 fixing bugs in the pre-release resolving code paths.
- Fix CacheControl import. (#357) #357
This release is a quick fix for a bootstrapping bug that inadvertently went out in 1.2.0 (Issue #354).
This release changes pex requirement resolution behavior. Only stable requirements are resolved by default now. The previous behavior that included pre-releases can be retained by passing –pre on the pex command line or passing allow_prereleases=True via the API.
- Add dummy flush method for clean interpreter exit with python3.6 (#343) #343
- Make PEX_PATH unify pex sources, as well as requirements. (#329) #329
- Repair passing of stdio kwargs to PEX.run(). (#288) #288
This release is a quick fix for a regression that inadvertently went out in 1.1.5 (Issue #243).
This release is a quick fix for a regression that inadvertently went out in 1.1.3 (Issue #216).
- Add a test for the regression in FixedEggMetadata._zipinfo_name and revert the breaking commit. Fixes #216
This release includes an initial body of work towards Windows support, ABI tag support for CPython 2.x and a fix for version number normalization.
- Add support for .pexrc files for influencing the pex environment. See the notes here. #128.
- Bug fix: PEX_PROFILE_FILENAME and PEX_PROFILE_SORT were not respected. #154.
- Adds the bdist_pex command to setuptools. #99.
- Bug fix: We did not normalize package names in ResolvableSet, so it was possible to depend on sphinx and Sphinx-1.4a0.tar.gz and get two versions build and included into the pex. #147.
- Adds a pex-identifying User-Agent. #101.
- Bug fix: Accommodate OSX Python python binaries. Previously the OSX python distributions shipped with OSX, XCode and available via https://www.python.org/downloads/ could fail to be detected using the PythonInterpreter class. Fixes #144.
- Bug fix: PEX_SCRIPT failed when the script was from a not-zip-safe egg. Original PR #139.
- Bug fix: sys.exit called without arguments would cause None to be printed on stderr since pex 1.0.1. #143.
- Bug fix: PEX-INFO values were overridden by environment Variables with default values that were not explicitly set in the environment. Fixes #135.
- Bug fix: Since 69649c1 we have been unpatching the side-effects of sys.modules after PEX.execute. This takes all modules imported during the PEX lifecycle and sets all their attributes to None. Unfortunately, sys.excepthook, atexit and __del__ may still try to operate using these tainted modules, causing exceptions on interpreter teardown. This reverts just the sys unpatching so that the abovementioned teardown hooks behave more predictably. Fixes #141.
- Allow PEXBuilder to optionally copy files into the PEX environment instead of hard-linking them.
- Allow PEXBuilder to optionally skip precompilation of .py files into .pyc files.
- Bug fix: PEXBuilder did not respect the target interpreter when compiling source to bytecode. Fixes #127.
- Bug fix: Fix complex resolutions when using a cache. Fixes: #120.
The 1.0.0 release of pex introduces a few breaking changes: pex -r now takes requirements.txt files instead of requirement specs, pex -s has now been removed since source specs are accepted as arguments, and pex -p has been removed in favor of its alias pex -o.
The pex command line interface now adheres to semver insofar as backwards incompatible CLI changes will invoke a major version change. Any backwards incompatible changes to the PEX environment variable semantics will also result in a major version change. The pex API adheres to semver insofar as backwards incompatible API changes will invoke minor version changes.
For users of the PEX API, it is recommended to add minor version ranges, e.g. pex>=1.0,<1.1. For users of the PEX CLI, major version ranges such as pex>=1,<2 should be sufficient.
- BREAKING CHANGE: Removes the -s option in favor of specifying directories directly as arguments to the pex command line.
- BREAKING CHANGE: pex -r now takes requirements.txt filenames and not requirement specs. Requirement specs are now passed as arguments to the pex tool. Use -- to escape command line arguments passed to interpreters spawned by pex. Implements #5.
- Adds a number of flag aliases to be more compatible with pip command lines: --no-index, -f, --find-links, --index-url, --no-use-wheel. Removes -p in favor of -o exclusively.
- Adds --python-shebang option to the pex tool in order to set the #! shebang to an exact path. #53.
- Adds support for PEX_PYTHON environment variable which will cause the pex file to reinvoke itself using the interpreter specified, e.g. PEX_PYTHON=python3.4 or PEX_PYTHON=/exact/path/to/interpreter. #27.
- Adds support for PEX_PATH environment variable which allows merging of PEX environments at runtime. This can be used to inject plugins or entry_points or modules from one PEX into another without explicitly building them together. #30.
- Consolidates documentation of PEX_ environment variables and adds the --help-variables option to the pex client. Partially addresses #13.
- Adds helper method to dump a package subdirectory onto disk from within a zipped PEX file. This can be useful for applications that know they’re running within a PEX and would prefer some static assets dumped to disk instead of running as an unzipped PEX file. #12.
- Now supports extras for static URLs and installable directories. #65.
- Adds -m and --entry-point alias to the existing -e option for entry points in the pex tool to evoke the similarity to python -m.
- Adds console script support via -c/--script/--console-script and PEX_SCRIPT. This allows you to reference the named entry point instead of the exact module:name pair. Also supports scripts defined in the scripts section of setup.py. #59.
- Adds more debugging information when encountering unresolvable requirements. #79.
- Bug fix: PEX_COVERAGE and PEX_PROFILE did not function correctly when SystemExit was raised. Fixes #81.
- Bug fix: Fixes caching in the PEX tool since we don’t cache the source distributions of installable directories. #24.
This is the last release before the 1.0.0 development branch is started.
- Change the setuptools range to >=2.2,<16 by handling EntryPoint changes as well as being flexible on whether pkg_resources is a package or a module. Fixes #55 and #34.
- Adds option groups to the pex tool to make the help output slightly more readable.
- Bug fix: Make pip install pex work better by removing extras_requires on the console_script entry point. Fixes #48
- New feature: Adds an interpreter cache to the pex tool. If the user does not explicitly disable the wheel feature and attempts to build a pex with wheels but does not have the wheel package installed, pex will download it in order to make the feature work. Implements #47 in order to fix #48
- Bug fix: Fixup string formatting in pex/bin/pex.py to support Python 2.6 Pull Request #40
- Performance improvement: Speed up the best-case scenario of dependency resolution. RB #1685
- Bug fix: Change from uuid4().get_hex() to uuid4().hex to maintain Python3 compatibility of pex.common. Pull Request #39
- Bug fix: Actually cache the results of translation. Previously bdist translations would be created in a temporary directory even if a cache location was specified. RB #1666
- Bug fix: Support all potential abi tag permutations when determining platform compatibility. Pull Request #33
- Performance improvement: Don’t always write packages to disk if they’ve already been cached. This can significantly speed up launching PEX files with a large number of non-zip-safe dependencies. RB #1642
- Bug fix: Allow pex 0.8.x to parse pex files produced by earlier versions of pex and twitter.common.python.
- Pin pex to setuptools prior to 9.x until we have a chance to make changes related to PEP440 and the change of pkg_resources.py to a package.
- Bug fix: Fix issue where it’d be possible to os.path.getmtime on a remote Link object Issue #29
- API change: Decouple translation from package iteration. This removes the Obtainer construct entirely, which likely means if you’re using PEX as a library, you will need to change your code if you were doing anything nontrivial. This adds a couple new options to resolve but simplifies the story around how to cache packages. RB #785
- Refactor http handling in pex to allow for alternate http implementations. Adds support for requests, improving both performance and security. For more information, read the commit notes at 91c7f32. RB #778
- Improvements to API documentation throughout.
- Renamed Tracer to TraceLogger to prevent nondeterministic isort ordering.
- Refactor tox.ini to increase the number of environment combinations and improve coverage.
- Adds HTTP retry support for the RequestsContext. RB #1303
- Make pex –version correct. Issue #19
- Bug fix: Fix over-aggressive sys.modules scrubbing for namespace packages. Under certain circumstances, namespace packages in site-packages could conflict with packages within a PEX, causing them to fail importing. RB #1378
- Bug fix: Replace uses of os.unsetenv(...) with del os.environ[...] Pull Request #11
- Bug fix: Scrub sys.path and sys.modules based upon both supplied path and realpath of files and directories. Newer versions of virtualenv on Linux symlink site-packages which caused those packages to not be removed from sys.path correctly. Issue #21
- Bug fix: The pex -s option was not correctly pulling in transitive dependencies. Issue #22
- Bug fix: Adds content method to HTTP contexts that does HTML content decoding, fixing an encoding issue only experienced when using Python 3. Issue #10
- Rename twitter.common.python to pex and split out from the twitter/commons repo.
- Change the interpretation of -i (and of PyPIFetcher’s pypi_base) to match pip’s -i. This is useful for compatibility with devpi.
Ensures that .egg/.whl distributions on disk have their mtime updated even though we no longer overwrite them. This gives them a new time lease against their ttl.
Without this change, once a distribution aged past the ttl it would never be used again, and builds would re-create the same distributions in tmpdirs over and over again.
Fixes an issue where SourceTranslator would overwrite .egg/.whl distributions already on disk. Instead it should always check to see if a copy already exists and reuse if there.
This ordinarily should not be a problem but the zipimporter caches metadata by filename instead of stat/sha, so if the underlying contents changed a runtime error would be thrown due to seemingly corrupt zip file offsets. RB #684
- Adds -i/--index option to the pex tool.
- Adds twitter.common.python.pex_bootstrap bootstrap_pex_env function in order to initialize a PEX environment from within a python interpreter. (Patch contributed by @kwlzn)
- Adds stdin=,stdout=,stderr= keyword parameters to the PEX.run function. (Patch from @benjy)
- The crawler now defaults to not follow links for security reasons. (Before the default behavior was to implicitly --follow-links for all requirements.) RB #293
- Improves scrubbing of site-packages from PEX environments. RB #289
0.5.1 - 0.5.4
- Adds twitter.common.python.finders which are additional finders for setuptools including: - find eggs within a .zip - find wheels within a directory - find wheels within a .zip RB #86
- Adds a new Package abstraction by refactoring Link into Link and Package. RB #92
- Adds support for PEP425 tagging necessary for wheel support. RB #87
- Improves python environment isolation by correctly scrubbing namespace packages injected into module __path__ attributes by nspkg pth files. RB #116
- Adds twitter.common.python.resolver resolve method that handles transitive dependency resolution better. This means that if the requirement futures==2.1.2 and an unqualified futures>=2 is pulled in transitively, our resolver will correctly resolve futures 2.1.2 instead of reporting a VersionConflict if any version newer than 2.1.2 is available. RB #129
- Factors all twitter.common.python test helpers into twitter.common.python.testing RB #91
- Bug fix: Fix OrderedSet atexit exceptions RB #147
- Bug fix: Fix cross-device symlinking (patch from @benjy)
- Bug fix: Raise a RuntimeError if we fail to write pkg_resources into a .pex RB #115
- Upgrade to setuptools>=1
- twitter.common.python is no longer a namespace package
- Kill the egg distiller. We now delegate .egg generation to bdist_egg. RB #55
- Plumb through the --zip-safe, --always-write-cache, --ignore-errors and --inherit-path flags to the pex tool.
- Delete the unused PythonDirWrapper code.
- Split PEXEnvironment resolution into twitter.common.python.environment and deconflate WorkingSet/Environment state.
- Removes the monkeypatched zipimporter in favor of keeping all eggs unzipped within PEX files. Refactors the PEX dependency cache in util.py
- Adds interpreter detection for Jython and PyPy.
- Dependency translation errors should be made uniform. (Patch from @johnsirois)
- Adds PEX_PROFILE_ENTRIES to limit the number of entries reported when PEX_PROFILE is enabled. (Patch from @rgs_)
- Bug fix: Several fixes to error handling in twitter.common.python.http (From Marc Abramowitz)
- Bug fix: PEX should not always assume that $PATH was available. (Patch from @jamesbroadhead)
- Bug fix: Filename should be part of the .pex cache key or else multiple identical versions will incorrectly resolve (Patch from @tc)
- Bug fix: Executed entry points shouldn’t be forced to run in an environment with __future__ imports enabled. (Patch from @lawson_patrick)
- Bug fix: Detect versionless egg links and fail fast. (Patch from @johnsirois.)
- Bug fix: Handle setuptools>=2.1 correctly in the zipimport monkeypatch (Patch from @johnsirois.)
- Bug fix: Fix handling of Fetchers with file:// urls.
- Adds the pex tool as a standalone tool.
- Bug fix: Bootstrapped twitter.common.python should declare twitter.common as a namespace package.
- Make twitter.common.python fully standalone by consolidating external dependencies within twitter.common.python.common.
- Initial published version of twitter.common.python.
Release history Release notifications
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size & hash||File type||Python version||Upload date|
|pex-1.6.10-py2.py3-none-any.whl (763.8 kB) View hashes||Wheel||3.7|
|pex-1.6.10.tar.gz (2.7 MB) View hashes||Source||None|