Install Pants Build System for Python

Pants is a fast and scalable build system for Python and other languages. It helps you manage dependencies, run tests, and package your code. This guide shows you how to install Pants for a Python project step by step.

What Is Pants Build System?

Pants is an open-source build tool created by Twitter and now maintained by a community. It handles monorepos well and supports Python, Java, Scala, and more. For Python developers, Pants simplifies dependency resolution, test execution, and code formatting.

Unlike pip or poetry, Pants works at the project level. It understands your entire codebase and builds only what changed. This saves time in large projects.

Prerequisites

Before you install Pants, make sure you have:

• Python 3.7 or higher installed
• pip package manager
• A terminal or command prompt
• A basic Python project structure

You can check your Python version with this command:

python --version

Output should look like:

Python 3.9.7

Step 1: Install Pants Using pip

The easiest way to install Pants is via pip. Open your terminal and run:

pip install pantsbuild.pants

This installs the latest stable version of Pants. Wait for the download to complete. You can verify the installation with:

pants --version

You should see something like:

pants version 2.18.0

If you see an error, try upgrading pip first:

pip install --upgrade pip

Step 2: Create a Pants Configuration File

Pants needs a configuration file at the root of your project. Create a file named pants.toml.

Here is a minimal example for a Python project:

[GLOBAL]
pants_version = "2.18.0"

[source]
root_patterns = ["/src"]

[python]
interpreter_constraints = [">=3.8"]

This tells Pants to use version 2.18.0, look for source code in the src folder, and require Python 3.8 or higher.

Step 3: Set Up Your Project Structure

Pants expects a certain folder layout. Create a src directory and inside it, add your Python modules.

Example structure:

my_project/
├── pants.toml
├── src/
│   ├── my_module/
│   │   ├── __init__.py
│   │   └── greet.py
│   └── BUILD
└── tests/
    ├── test_greet.py
    └── BUILD

The __init__.py file can be empty. The BUILD files tell Pants what to do with each directory.

Step 4: Write BUILD Files

BUILD files define targets. For Python code, you use the python_sources function. Create a src/BUILD file:

# src/BUILD
python_sources(
    name="my_module",
    sources=["**/*.py"],
)

This target includes all Python files in the src folder. For tests, create tests/BUILD:

# tests/BUILD
python_tests(
    name="tests",
    sources=["**/*.py"],
)

The python_tests function marks these files as test targets.

Step 5: Add Source Code and Tests

Create a simple module in src/my_module/greet.py:

# src/my_module/greet.py
def greet(name: str) -> str:
    """Return a greeting message."""
    return f"Hello, {name}!"

Now write a test in tests/test_greet.py:

# tests/test_greet.py
from my_module.greet import greet

def test_greet():
    result = greet("Alice")
    assert result == "Hello, Alice!"

Step 6: Run Pants Commands

Now you are ready to use Pants. Run all tests with:

pants test ::

The :: means all targets. You should see output like:

13:28:33 [INFO] Completed: Run tests for //tests:tests
✓ tests/test_greet.py::test_greet passed in 0.02s

To check your code for issues, use the lint command:

pants lint ::

Pants will run tools like flake8 if configured.

Step 7: Install Dependencies

To add external packages, use the python_requirement function in your BUILD file. For example, to use requests:

# src/BUILD
python_sources(
    name="my_module",
    sources=["**/*.py"],
    dependencies=[
        "//:requests",
    ],
)

Then create a python_requirement target at the root:

# BUILD at project root
python_requirement(
    name="requests",
    requirements=["requests>=2.28"],
)

Pants will resolve and download dependencies automatically when you build or test.

Step 8: Package Your Code

To create a distributable package, use the package command:

pants package ::

This generates a wheel file in the dist folder. You can then install it with pip or upload to PyPI.

Common Issues and Fixes

If you get a "command not found" error, ensure Pants is in your PATH. You can add it by reinstalling or using python -m pants.

If Pants says "no targets found", check your BUILD files. Make sure they are in the correct directories and have valid syntax.

For dependency errors, verify that your python_requirement targets match the package names exactly.

Conclusion

Installing Pants build system for Python is straightforward. Start with pip install pantsbuild.pants, create a pants.toml file, and write BUILD targets for your modules and tests. Pants then handles dependency management, testing, and packaging efficiently. For beginners, the key steps are setting up the configuration and understanding BUILD files. Once mastered, Pants scales well for large Python projects and monorepos.

Practice by adding more modules and tests. Use the pants help command to explore other features like formatting or type checking. Pants improves your workflow by automating repetitive tasks.