run

Run a pex_binary target.

---

To run an executable/script, simply use ./pants run on a pex_binary target, like this:

$ ./pants run project/app.py

or

$ ./pants run project:app

You may only run one target at a time.

The program will have access to the same environment used by the parent ./pants process, so you can set environment variables in the external environment, e.g. FOO=bar ./pants run project/app.py. (Pants will auto-set some values like $PATH).

Tip: check the return code

Pants will propagate the return code from the underlying executable. Run echo $? after the Pants run to see the return code.

Tip: Using the IntelliJ/PyCharm remote debugger

First, add the following target in some BUILD file (e.g., the one containing your other 3rd-party dependencies):

python_requirement_library(
  name = "pydevd-pycharm",
  requirements=["pydevd-pycharm==203.5419.8"],  # Or whatever version you choose.
)

You can check this into your repo, for convenience.

Now, use the remote debugger as usual:

1. Start a Python remote debugging session in PyCharm, say on port 5000.

2. Add the following code at the point where you want execution to pause and connect to the debugger:

import pydevd_pycharm
pydevd_pycharm.settrace('localhost', port=5000, stdoutToServer=True, stderrToServer=True)

Run your executable with ./pants run as usual.

Note: The first time you do so you may see some extra dependency resolution work, as pydevd-pycharm has now been added to the binary's dependencies, via inference. If you have dependency inference turned off in your repo, you will have to manually add a temporary explicit dependency in your binary target on the pydevd-pycharm target.

Issues finding files?

Run ./pants dependencies --transitive path/to/binary.py to ensure that all the files you need are showing up, including for any resources you intend to use.

Passing arguments

To pass arguments to the script/executable, use -- at the end of the command, like this:

$ ./pants run project/app.py -- --arg1 arg2 arg3