Installing Pants

---

You can download and run an installer script that will install the Pants binary with this command:

curl --proto '=https' --tlsv1.2 -fsSL https://static.pantsbuild.org/setup/get-pants.sh | bash

This script will install pants into ~/bin, which must be on your PATH. The installer script will warn you if it is not.

For security reasons, we don't recommend frequently curling this script directly to bash, e.g., on every CI run. If the script were compromised during some time window, you'd be more likely to download it during that window and be impacted. Instead, for regular use, we recommend checking this script into the root of your repo and pointing users and CI machines to that checked-in version. The script is very simple and need not be updated very often.

Alternatively, on macOS you can also use homebrew to install pants:

brew install pantsbuild/tap/pants

You can also use the bin tool to install pants:

bin i github.com/pantsbuild/scie-pants ~/.local/bin/pants

pants is a launcher binary that delegates to the underlying version of Pants in each repo. This allows you to have multiple repos, each using an independent version of Pants.

• If you run pants in a repo that is already configured to use Pants, it will read the repo's Pants version from the pants.toml config file, install that version if necessary, and then run it.

• If you run pants in a repo that is not yet configured to use Pants, it will prompt you to set up a skeleton pants.toml that uses that latest stable version of Pants. You'll then need to edit that config file to add initial configuration.

If you have difficulty installing Pants, see our getting help for community resources to help you resolve your issue.

Upgrading Pants

The pants launcher binary will automatically install and use the Pants version specified in pants.toml, so upgrading Pants in a repo is as simple as editing pants_version in that file.

To upgrade the pants launcher binary itself, run

SCIE_BOOT=update pants

Running Pants from unreleased builds

To use an unreleased build of Pants from the pantsbuild/pants main branch, locate the main branch SHA, set PANTS_SHA=\<SHA> in the environment, and run pants as usual:

PANTS_SHA=8553e8cbc5a1d9da3f84dcfc5e7bf3139847fb5f pants --version

If a particular SHA does not have built wheels, you can either wait for the next release from the relevant branch, ping a maintainer in Slack, or file a Github issue mentioning the SHA that you would like to test.

Running Pants from sources

See here for instructions on how to run Pants directly from its sources.

This is useful when making changes directly to Pants, to see how those changes impact your repo.

The old ./pants script

Before the creation of the pants launcher binary, the recommended way of installing Pants was to check a ./pants launcher script into each repo. This script required an external Python interpreter, and was prone to errors and issues related to discovery and use of this interpreter.

The pants launcher binary uses an embedded interpreter and does not rely on one being present on the system (although if your repo contains Python code then it naturally requires a Python interpreter).

We strongly recommend removing the ./pants script from your repo and using the pants binary instead. You can keep a simple ./pants script that delegates to pants to ease the transition. However, if you do need to continue to use the old installation method for some reason, it is described here. But please let us know so we can accommodate your use case in the launcher binary.

The pants binary's implementation

You don't need to know this to use pants, but it may be of interest:

The pants launcher binary is also known as scie-pants (pronounced "ski pants"), It's implemented using scie, a Self Contained Interpreted Executable launcher. scie is what allows pants to embed its own Python interpreter, instead of relying on a specific interpreter being available on your PATH.

In fact, instead of literally embedding an interpreter in the pants binary, which would inflate its size, the binary is "hollowed out": Instead of the interpreter itself it contains metadata on how to download a platform-specific standalone interpreter executable. The scie mechanism then downloads that interpreter file on first use, and caches it for future use. So if you update the pants launcher binary, you don't have to re-download the interpreter.

See the links above for more details. We hope to soon add support in Pants for building scies out of your code, which will allow you to package and ship fully standalone Python binaries!