Skip to main content
Version: 2.34 (dev)

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:

  • Determine your operating system and architecture (x86 or ARM)
  • Download the appropriate pants from GitHub and validates its fingerprint
  • Install pants into ~/.local/bin
  • Warn you if ~/.local/bin is not on your PATH
Warning

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.

The pants binary 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 can then update that file with your initial configuration.

Alternative Installation Methods​

Using Homebrew on MacOS (ARM):

brew install pantsbuild/tap/pants

Using bin:

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

Using the GitHub CLI, specifying your operating system and architecture:

# Using `macos-aarch64` here, other options are: `linux-aarch64`, `linux-x86_64`
gh release download \
    --repo pantsbuild/scie-pants \
    --pattern "*macos-aarch64" \
    --output ~/.local/bin/pants

# Check attestations for "✓ Verification succeeded!"
gh attestation verify ~/.local/bin/pants \
    --repo pantsbuild/scie-pants \
    --signer-repo pantsbuild/scie-pants

# Allow running pants
chmod +x ~/.local/bin/pants

Using wget:

# os-arch: `linux-aarch64`, `linux-x86_64`, or `macos-aarch64`
wget https://github.com/pantsbuild/scie-pants/releases/download/{release_version}/scie-pants-{os-arch}
wget https://github.com/pantsbuild/scie-pants/releases/download/{release_version}/scie-pants-{os-arch}.sha256

# Verify SHA with `shasum -a 256` or `sha256sum`
shasum -a 256 -c ./*.sha256

# Allow running pants
mv scie-pants-{os-arch} ~/.local/bin/pants
chmod +x ~/.local/bin/pants

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, either:

  • Use the package manager you used to install Pants. For example, with Homebrew: brew update && brew upgrade pantsbuild/tap/pants.
  • Use its built-in self-update functionality: SCIE_BOOT=update pants.

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, 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.