What are source roots?

Many programming languages organize code into packages. Usually, the packages form a hierarchy that mirrors the filesystem structure in which the source files live.

For example, this set of Python source files:

src/python/foo/foo.py
src/python/foo/bar/bar.py
src/python/baz/qux/quux/quux.py

Is organized into the following packages:

foo
foo.bar
baz.qux.quux

To understand your code's package structure, Pants needs to know about source_roots: the points in the filesystem that represent package roots. In the example above, src/python/ is a source root. So when some code says from import foo.bar import bar, Pants can know that this corresponds to the code in src/python/foo/bar/bar.py.

Configuring source roots

There are two ways to configure source roots:

Using patterns
Using marker files

Configuring source roots using patterns

You can provide a set of patterns that match your source roots:

[source]
root_patterns = [
  'src/python',
  'test/python',
]

A directory whose suffix matches a root will be considered a source root for any code under it. So the example above will consider all of these to be source roots, if they exist:

<repo root>/src/python
<repo root>/test/python
<repo root>/project1/src/python
<repo root>/project1/test/python

If you want to anchor the source root so that it only matches at the build root, precede it with /:

[source]
root_patterns = [
  '/src/python',
]

This will match <repo root>/src/python but not <repo root>/project1/src/python.

📘
Marking the repository root as a source root
It's common in smaller Python codebases for the root of the repository to be a source root. To configure that, use this in your pants.toml:
[source]
root_patterns = ['/']

📘
Default source roots
The default value of the root_patterns config key is ["/", "src", "src/python", "src/py"].
These capture a range of common cases, including a source root at the root of the repository. If your source roots match these patterns, you don't need to explicitly configure them.

Configuring source roots using marker files

You can also denote your source roots using specially-named marker files. To do so, first pick a name (or multiple names) to use:

[source]
marker_filenames = ['SOURCE_ROOT']

Then place a file of that name in each of the source roots. The contents of those files don't matter. They can be empty.

Note that you can mix root_patterns and marker_filenames. Pants will use both.

📘
Using setup.py as a marker file
In some Python repos there may already be a setup.py file at each source root. You can simply treat those as marker files:
[source]
marker_filenames = ['setup.py']

You can use ./pants roots to view the current set of source roots.