Hey! These docs are for version 2.8, which is no longer officially supported. Click here for the latest version, 2.18!

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.