DocsCommunityTestimonialsUsersGitHubTwitterBlogJobs
HomeDocs
DocsCommunityTestimonialsUsersGitHubTwitterBlogJobsTermsPrivacyCookies
TermsPrivacyCookies
Hey! These docs are for version 2.12, which is no longer officially supported. Click here for the latest version, 2.18!

Go and Shell can skip this page

Go does have a notion of source roots: where your `go.mod` is located. However, that is handled automatically by Pants without you needing to follow this page.

Shell does not have any notion of source roots.

# What are 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. _Source roots_ are a generic equivalent of these concepts.

For example, given this Python project:


You would likely set `PYTHONPATH=src/python` and use imports like this:

In the example above, `src/python` is a source root. So, when some code says `from project.app import App`, Pants can know that this corresponds to the code in `src/python/project/app.py`.
# Configuring source roots
There are two ways to configure source roots:
  • Using patterns
  • Using marker files
You can mix and match between both styles. Run `./pants roots` to see what Pants is using:

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

The `/` prefix means that the source root is located at the build root, so it will match `src/python`, but not `project1/src/python`.
You can leave off the `/` prefix to match any directory whose suffix matches a pattern. For example, `root_patterns = ["src/python"]` would consider all of these to be source roots, if they exist:
  • `src/python`
  • `project1/src/python`
You can use `*` as a glob. For example, `root_patterns = ["/src/*"]` would consider all of these to be source roots:
  • `src/python`
  • `src/java`
  • `src/assets`
### Configuring no source roots
Many projects do not have any top-level folders used for namespacing.
For example, given this Python project:

You would likely _not_ set `PYTHONPATH` and would still use imports like this:

If you have no source roots, use this config:

Default source roots
The default value of the `root_patterns` config key is `["/", "src", "src/python", "src/py", "src/java", "src/scala", "src/thrift", "src/protos", "src/protobuf"]`. 
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:

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.
For example, given this Python repo, where we have a `setup.py` for each distinct project:

We could use this config:

We can then run `./pants roots` to find these source roots used:

This means that Pants would work with these imports:

Whereas these imports are invalid:

# Examples
These project structures are all valid; Pants does not expect you to reorganize your codebase to use the tool. 
## `src/<lang>` setup
This setup is common in "polyglot" repositories: i.e. repos with multiple languages.
### Project:

While we have tests in a separate source root here, it's also valid to have tests colocated with their src files.
### Example imports:


### Config:

Note that we organized our 3rdparty requirements in the top-level folders `3rdparty/python` and `3rdparty/java`, but we do not need to include them as source roots because we do not have any first-party code there.
## Multiple top-level projects
### Project:
This layout has lots of nesting; this is only one possible way to organize the repository.

### Example imports:

Note that even though the projects live in different top-level folders, you are still able to import from other projects. If you would like to limit this, you can use `./pants dependees` or `./pants dependencies` in CI to track where imports are being used. See [Project introspection](🔗).
### Config:
Either of these are valid and they have the same result:


## No source root
Warning: while this project structure is valid, it often does not scale as well as your codebase grows, such as adding new languages.
### Project:

### Example imports:

### Config:
Either of these are valid and they have the same result: