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.toml
`
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.toml
` file:
where `$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
`, `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.