Pants has a robust options system, allowing you to configure hundreds of options. Every Pants option can be set via a command-line flag, an environment variable, or, most commonly, a config file.
The options system is described in detail [here](🔗). This page will set up your initial Pants config file.
# 1. Create `
Pants configuration lives in a file called `
pants.toml` in the root of the repo. This file uses the [TOML](🔗) format.
If you haven't yet, create a `
$PANTS_VERSION` is the version of Pants you want to pin your repo to. When you'd like to upgrade Pants, edit `
pants_version` and the `
./pants` script will self-update on the next run.
# 2. Configure source roots
Some project layouts use top-level folders for namespace purposes, but have the code live underneath. However, the code's imports will ignore these top-level folders, thanks to mechanisms like the `
$PYTHONPATH` and the JVM classpath. For example, to import the file `
src/my_project/app.py`, many projects use `
import my_project.app`, rather than `
import src.my_project.app`. _Source roots_ are how Pants understands these imports.
By default, Pants recognizes having no source root, or having `
src/python`, or `
src/py` as source roots. If your project has a different structure, see [Source roots](🔗) for how to configure them, and for examples of different project structures with Pants.
Golang projects can skip this step
Golang projects already use `
go.mod` as an equivalent to "source roots".
# 3. Enable backends
Most Pants functionality is provided via pluggable [_backends_](🔗), which are activated by adding to the `
[GLOBAL].backend_packages` option like this:
# 4. Generate BUILD files
Finally, once you have enabled the backends for the language(s) you'd like to use, run [`
./pants tailor`](🔗) to generate BUILD files for Pants to know which code to operate on.