### Example of bdist_pex --bdist-all output

Source: https://github.com/pex-tool/pex/blob/main/docs/buildingpex.md

This example shows the console output after running `bdist_pex --bdist-all`, demonstrating the creation of executables for various Sphinx commands.

```console
$ git clone https://github.com/sphinx-doc/sphinx && cd sphinx
$ python setup.py bdist_pex --bdist-all --bdist-dir=$HOME/bin
running bdist_pex
Writing sphinx-apidoc to /Users/wickman/bin/sphinx-apidoc
Writing sphinx-build to /Users/wickman/bin/sphinx-build
Writing sphinx-quickstart to /Users/wickman/bin/sphinx-quickstart
Writing sphinx-autogen to /Users/wickman/bin/sphinx-autogen
$ sphinx-apidoc --help | head -1
Usage: sphinx-apidoc [options] -o <output_path> <module_path> [exclude_path, ...]
```

--------------------------------

### Install BusyBox SCIE tools to the PATH

Source: https://github.com/pex-tool/pex/blob/main/docs/scie.md

Use the `SCIE=install` environment variable with the BusyBox SCIE to install its bundled commands to a specified directory, making them accessible directly from the system's PATH.

```sh
:; mkdir /tmp/bin
:; export PATH=/tmp/bin:$PATH
:; SCIE=install ./tools /tmp/bin
:; ls -1 /tmp/bin/
cowsay
json
uuid
:; which cowsay
/tmp/bin/cowsay
:; cowsay Moo!
  ____
| Moo! |
  ====
    \
     \
       ^__^
       (oo)\
       (__)\\       )\/\n           ||----w |
           ||     ||

```

--------------------------------

### Install PEX with Requests Extra

Source: https://github.com/pex-tool/pex/blob/main/docs/recipes.md

Install PEX with the 'requests' extra to enable proxy support for fetching dependencies. This is a prerequisite for using environment variables for proxy configuration.

```bash
$ pip install pex[requests]
```

--------------------------------

### Run Lazy PEX SCIE with Custom URL (Failing Example)

Source: https://github.com/pex-tool/pex/blob/main/docs/scie.md

Attempts to run a lazy PEX scie with a custom URL set via `PEX_BOOTSTRAP_URLS`. This example demonstrates a failure scenario where the downloaded file has an unexpected hash, indicating a mismatch in content.

```sh
:; PEX_BOOTSTRAP_URLS=pythons.json ./cowsay Moo!
```

--------------------------------

### Package Uvicorn App with PEX

Source: https://github.com/pex-tool/pex/blob/main/docs/recipes.md

Package a uvicorn-powered server with your app coroutine into a PEX file. This example injects arguments to configure the server's port.

```bash
$ pex "uvicorn[standard]" -c uvicorn --inject-args 'example:app --port 8888' -oexample-app.pex
$ ./example-app.pex
INFO:     Started server process [2014]
INFO:     Waiting for application startup.
INFO:     ASGI 'lifespan' protocol appears unsupported.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8888 (Press CTRL+C to quit)
^CINFO:     Shutting down
INFO:     Finished server process [2014]
```

```bash
$ ./example-app.pex --port 0
INFO:     Started server process [2248]
INFO:     Waiting for application startup.
INFO:     ASGI 'lifespan' protocol appears unsupported.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:45751 (Press CTRL+C to quit)
```

--------------------------------

### Run PEX Test Suite

Source: https://github.com/pex-tool/pex/blob/main/README.rst

Executes the PEX test suite using uv and dev-cmd. Assumes uv is installed.

```bash
$ uv run dev-cmd
```

--------------------------------

### Install PEX App in a Docker Container

Source: https://github.com/pex-tool/pex/blob/main/docs/recipes.md

Build a PEX application for use in a Docker container using a multi-stage build. This approach minimizes container footprint and optimizes application startup time by installing the PEX as a venv.

```dockerfile
FROM python:3.10-slim as deps
COPY /my-app.pex /
RUN PEX_TOOLS=1 /usr/local/bin/python3.10 /my-app.pex venv --scope=deps --compile /my-app

FROM python:3.10-slim as srcs
COPY /my-app.pex /
RUN PEX_TOOLS=1 /usr/local/bin/python3.10 /my-app.pex venv --scope=srcs --compile /my-app

FROM python:3.10-slim
COPY --from=deps /my-app /my-app
COPY --from=srcs /my-app /my-app
ENTRYPOINT ["/my-app/pex"]
```

--------------------------------

### Create a Flask application script

Source: https://github.com/pex-tool/pex/blob/main/docs/buildingpex.md

Define a simple Flask web application that listens for requests on the root URL and returns 'hello world!'. This script is used as an example entry point for PEX.

```python
from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello_world():
    return 'hello world!'

app.run()

```

--------------------------------

### Invoke PEX with a Python script as entry point

Source: https://github.com/pex-tool/pex/blob/main/docs/buildingpex.md

Execute a Python script (e.g., a Flask application) using `pex`, specifying the script as the entry point after any options. This starts the Flask development server.

```console
$ pex flask -- ./flask_hello_world.py
 * Serving Flask app '__main__'
 * Debug mode: off
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on http://127.0.0.1:5000
Press CTRL+C to quit

```

--------------------------------

### Specify requirements for PEX environment

Source: https://github.com/pex-tool/pex/blob/main/docs/buildingpex.md

Start an interactive PEX environment with specified dependencies like 'flask' and 'psutil>1'. Requirements are specified using pip-compatible formats.

```console
$ pex flask 'psutil>1'
Pex 2.16.1 ephemeral hermetic environment with 2 requirements and 8 activated distributions.
Python 3.11.9 (main, Apr 26 2024, 19:20:24) [GCC 13.2.0] on linux
Type "help", "pex", "copyright", "credits" or "license" for more information.
>>>

```

--------------------------------

### Build all console scripts with bdist_pex

Source: https://github.com/pex-tool/pex/blob/main/docs/buildingpex.md

Use `bdist_pex --bdist-all` in `setup.py` to build all console scripts defined in a package. This is useful for installing executables without version numbers or suffixes, allowing them to be placed on the system's PATH.

```console
python setup.py bdist_pex --bdist-all --bdist-dir=$HOME/bin
```

--------------------------------

### Invoke console script 'mturk' with pex

Source: https://github.com/pex-tool/pex/blob/main/docs/buildingpex.md

Example of running a console script 'mturk' from the 'boto' distribution using `python2.7 -mpex -c mturk`. This demonstrates invoking scripts defined in the 'scripts' section of a distribution.

```console
$ python2.7 -mpex boto -c mturk
usage: mturk [-h] [-P] [--nicknames PATH]
             {bal,hit,hits,new,extend,expire,rm,as,approve,reject,unreject,bonus,notify,give-qual,revoke-qual}
             ...
mturk: error: too few arguments
```

--------------------------------

### Build and Serve Documentation Locally

Source: https://github.com/pex-tool/pex/blob/main/CONTRIBUTING.md

Use this command to build the full documentation site, including a PDF version and search index. Browse the site locally to review changes.

```bash
uv run dev-cmd docs -- --linkcheck --pdf --serve
```

--------------------------------

### Install PEX using pip

Source: https://github.com/pex-tool/pex/blob/main/README.rst

Installs the PEX tool using pip. This is the standard method for adding PEX to your Python environment.

```bash
$ pip install pex
```

--------------------------------

### Launch Sphinx with Entry Point

Source: https://github.com/pex-tool/pex/blob/main/README.rst

Launches Sphinx in an ephemeral PEX environment using its 'main' entry point. The '-- --help' passes arguments to the Sphinx command.

```bash
$ pex sphinx -e sphinx:main -- --help
```

--------------------------------

### Create PEX, SH-Boot PEX, and SCIE PEX

Source: https://github.com/pex-tool/pex/blob/main/docs/scie.md

This command demonstrates how to create three different types of PEX files: a traditional PEX, a PEX with a shell boot script, and a SCIE PEX with an eager Python interpreter. Use the `--scie eager` flag to generate a native executable that bundles a Python interpreter.

```sh
pex cowsay -c cowsay --inject-args=-t --venv -o cowsay.pex
```

```sh
pex cowsay -c cowsay --inject-args=-t --venv --sh-boot -o cowsay-sh-boot.pex
```

```sh
pex cowsay -c cowsay --inject-args=-t --venv --scie eager -o cowsay
```

--------------------------------

### Build PEX from source using uv

Source: https://github.com/pex-tool/pex/blob/main/README.rst

Builds a PEX binary from a git clone using uv and dev-cmd. The resulting binary can be copied to your PATH.

```bash
$ uv run dev-cmd package
$ cp dist/pex ~/bin
```

--------------------------------

### Create PEX with Platform Placeholder

Source: https://github.com/pex-tool/pex/blob/main/CHANGES.md

Demonstrates how to use the `{platform}` placeholder in PEX file names to generate platform-specific PEX files. This is useful for managing different platform builds.

```console
:; python -mpex ansicolors -o "ansicolors-{platform}.pex"

:; ./ansicolors-py2.py3-none-any.pex
Pex 2.83.0 hermetic environment with 1 requirement and 1 activated distribution.
Python 3.14.2 (main, Dec  5 2025, 14:39:48) [GCC 15.2.0] on linux
Type "help", "pex", "copyright", "credits" or "license" for more information.
>>> pex()
Running from PEX file: ./ansicolors-py2.py3-none-any.pex
Requirements:
  ansicolors
Activated Distributions:
  ansicolors-1.1.8-py2.py3-none-any.whl
>>>

:; python -mpex \
    --complete-platform package/complete-platforms/linux-x86_64.json \
    --complete-platform package/complete-platforms/macos-aarch64.json ansible \
    -o "ansible-{platform}.pex"

:; ./ansible-cp314-cp314-macosx_11_0_arm64.manylinux2014_x86_64.pex
Pex 2.83.0 hermetic environment with 1 requirement and 10 activated distributions.
Python 3.14.2 (main, Dec  5 2025, 14:39:48) [GCC 15.2.0] on linux
Type "help", "pex", "copyright", "credits" or "license" for more information.
>>> pex()
Running from PEX file: ./ansible-cp314-cp314-macosx_11_0_arm64.manylinux2014_x86_64.pex
Requirements:
  ansible
Activated Distributions:
  ansible-13.2.0-py3-none-any.whl
  ansible_core-2.20.1-py3-none-any.whl
  jinja2-3.1.6-py3-none-any.whl
  markupsafe-3.0.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
  pyyaml-6.0.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
  cryptography-46.0.3-cp311-abi3-manylinux_2_34_x86_64.whl
  cffi-2.0.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
  pycparser-2.23-py3-none-any.whl
  packaging-25.0-py3-none-any.whl
  resolvelib-1.2.1-py3-none-any.whl
>>>
```

--------------------------------

### Generate Starter JSON for Alternate URLs

Source: https://github.com/pex-tool/pex/blob/main/docs/scie.md

Inspects a PEX scie to generate a starter JSON file containing default entries for alternate Python distribution URLs. This file can then be edited to point to custom locations.

```sh
:; SCIE=inspect ./cowsay | jq '{ptex:.ptex}' > starter.json
```

--------------------------------

### Run Integration Tests with Specific Python Versions

Source: https://github.com/pex-tool/pex/blob/main/CONTRIBUTING.md

Execute integration tests against different Python interpreters. Ensure the specified Python version is installed on your system.

```bash
uv run dev-cmd test-py311-integration
```

```bash
uv run dev-cmd test-py27-integration
```

```bash
uv run dev-cmd test-pypy310-integration
```

--------------------------------

### Build a PEX SCIE BusyBox with multiple commands

Source: https://github.com/pex-tool/pex/blob/main/docs/scie.md

Use the `--scie-busybox` flag with a comma-separated list of entry points to create a PEX SCIE that bundles multiple commands. Entry points can be specified as module=module:function, module, or console script names.

```sh
:; pex cowsay -c cowsay --inject-args=-t --scie lazy --scie-busybox json=json.tool,uuid=uuid:uuid4,cowsay -otools
```

--------------------------------

### Create a PEX file from a requirements.txt file

Source: https://github.com/pex-tool/pex/blob/main/docs/buildingpex.md

Build a PEX file named 'my_application.pex' by specifying a 'requirements.txt' file using the `-r` flag. This mirrors the functionality of `pip` for dependency management.

```console
$ pex -r requirements.txt -o my_application.pex
```

--------------------------------

### Run Unit Tests with Specific Python Versions

Source: https://github.com/pex-tool/pex/blob/main/CONTRIBUTING.md

Execute unit tests against different Python interpreters. Ensure the specified Python version is installed on your system.

```bash
uv run dev-cmd test-py311
```

```bash
uv run dev-cmd test-py27
```

```bash
uv run dev-cmd test-pypy310
```

--------------------------------

### Scope Index/Find-Links for Specific Platforms

Source: https://github.com/pex-tool/pex/blob/main/CHANGES.md

Scope `--index` and `--find-links` repositories to specific environments. This example restricts the piwheels index to armv7l machines.

```console
--index piwheels=https://www.piwheels.org/simple --source piwheels=platform_machine == 'armv7l'
```

--------------------------------

### Run PEX Files with Different Bootstrapping

Source: https://github.com/pex-tool/pex/blob/main/docs/scie.md

Demonstrates running PEX files with different bootstrapping methods: traditional Python shebang, sh-boot, and hermetic scie boot. The hermetic scie boot works even when Python is not found on the PATH.

```sh
# Traditional Python shebang boot:
:; env -i PATH= ./cowsay.pex Moo!
```

```sh
# A --sh-boot /bin/sh boot:
:; env -i PATH= ./cowsay-sh-boot.pex Moo!
```

```sh
# A hermetic scie boot:
:; env -i PATH= ./cowsay Moo!
```

--------------------------------

### Run Pytest with Passthrough Arguments

Source: https://github.com/pex-tool/pex/blob/main/README.rst

Use this command to run integration tests with pytest, passing specific arguments like '-k' to filter tests. Ensure you have the 'uvrc' tool installed.

```bash
$ uvrc test-py37-integration -- -k test_reproducible_build
```

--------------------------------

### Run a BusyBox SCIE and select a command

Source: https://github.com/pex-tool/pex/blob/main/docs/scie.md

When a BusyBox SCIE is executed without a specified command, it lists the available boot commands. You can select a command by setting the SCIE_BOOT environment variable or passing it as the first argument.

```sh
:; ./tools
Error: Could not determine which command to run.

Please select from the following boot commands:

cowsay
json
uuid

You can select a boot command by setting the SCIE_BOOT environment variable or else by passing it as the 1st argument.
```

--------------------------------

### Test PEX Fetching with Proxy

Source: https://github.com/pex-tool/pex/blob/main/docs/recipes.md

Verify that PEX can fetch dependencies through the configured proxy by running a simple PEX command. Verbose output helps in debugging proxy issues.

```bash
$ pex -v pex
```

--------------------------------

### Run Pex from Source

Source: https://github.com/pex-tool/pex/blob/main/README.rst

Invoke Pex directly from its source code using the Python interpreter. This is useful when you need to run Pex without it being installed or available on your system's PATH.

```bash
$ python -m pex
```

--------------------------------

### Adding Background Colors and Styles

Source: https://github.com/pex-tool/pex/blob/main/pex/vendor/_vendored/ansicolors/ansicolors-1.1.8.dist-info/DESCRIPTION.rst

Shows how to apply background colors and text styles like underline using the `bg` and `style` arguments. These can be combined.

```python
print(red('red on blue', bg='blue'))
print(green('green on black', bg='black', style='underline'))
```

--------------------------------

### Specify explicit Python shebang for PEX

Source: https://github.com/pex-tool/pex/blob/main/docs/buildingpex.md

Use the --python-shebang option to set an explicit Python interpreter path for the PEX file's hashbang, useful for non-standard Python installations.

```console
$ pex --python-shebang='/Users/wickman/Python/CPython-3.4.2/bin/python3.4' -o my.pex
$ head -1 my.pex
#!/Users/wickman/Python/CPython-3.4.2/bin/python3.4
```

--------------------------------

### Execute Pex Commands Using Dockerized Environment

Source: https://github.com/pex-tool/pex/blob/main/CONTRIBUTING.md

Replace 'uv run dev-cmd' with './duvrc.sh' to execute Pex commands within a Docker container. This is useful for running tests against Python versions not installed locally.

```bash
./duvrc.sh test-py27 ...
```