Pants: Build System Commands Reference

Pantsbuild Usage

Pantsbuild Usage

Pants is a fast, scalable, user-friendly build system for codebases of all sizes. It orchestrates dozens of standard tools and provides unified interface for developers.

Basic Commands

List All Targets

pants list ::

List targets in a specific directory:

pants list src/python/myapp::

Run Tests

Run all tests:

pants test ::

Run tests for a specific target:

pants test src/python/myapp:tests

Run tests with coverage:

pants test --coverage-py-report=html ::

Format Code

Format all code:

pants fmt ::

Format specific files:

pants fmt src/python/myapp/main.py

Lint Code

pants lint ::

Lint specific targets:

pants lint src/python/myapp::

Type Checking

pants check ::

Build Package

pants package ::

Build specific target:

pants package src/python/myapp:app

Run Application

pants run src/python/myapp:main

Common Configuration

pants.toml

Basic configuration file structure:

[GLOBAL]
pants_version = "2.20.0"
backend_packages = [
  "pants.backend.python",
  "pants.backend.python.lint.black",
  "pants.backend.python.lint.isort",
  "pants.backend.python.typecheck.mypy",
]

[python]
interpreter_constraints = ["==3.11.*"]
enable_resolves = true
resolves = { python-default = "3rdparty/python/default.lock" }

[python-infer]
# Enable imports inference
imports = true
inits = true

[black]
config = "pyproject.toml"

[isort]
config = [".isort.cfg"]

[mypy]
config = "mypy.ini"

BUILD File Example

# src/python/myapp/BUILD

python_sources(
    name="lib",
)

python_tests(
    name="tests",
    sources=["*_test.py", "test_*.py"],
)

pex_binary(
    name="app",
    entry_point="main.py",
)

Advanced Features

Dependencies Between Targets

Pants automatically infers dependencies from imports, but you can also explicitly declare them:

python_sources(
    name="lib",
    dependencies=[
        "src/python/otherapp:lib",
        "3rdparty/python#requests",
    ],
)

Multiple Python Resolves

Define multiple lock files for different parts of your codebase:

[python]
resolves = {
  python-default = "3rdparty/python/default.lock",
  python-data-science = "3rdparty/python/data-science.lock",
}

Then specify which resolve to use:

python_sources(
    name="lib",
    resolve="python-data-science",
)

Custom Tool Configuration

Override tool versions:

[black]
version = "black==23.3.0"
args = ["--line-length=100"]

[pytest]
args = ["-vv", "--tb=short"]

Useful Workflows

Pre-commit Hook

Run Pants checks before commit:

pants --changed-since=HEAD lint check

CI/CD Integration

# In CI pipeline
pants --changed-since=origin/main lint check test

Generate Lockfile

pants generate-lockfiles --resolve=python-default

Peek at Target Metadata

pants peek src/python/myapp:lib

Show Dependencies

pants dependencies src/python/myapp:lib

Show reverse dependencies (dependees):

pants dependees src/python/myapp:lib

Performance Tips

Use --changed-since to only process changed files
Enable remote caching for shared builds
Use --filter to run specific types of targets
Leverage pants.toml to set project-wide defaults

Troubleshooting

Clear Cache

pants clean-all

Debug Target Resolution

pants --print-stacktrace list src/python/myapp::

Validate Configuration

pants validate ::