We recommend using an incremental migration to adopt Pants, as it will help to ensure that your builds keep behaving how you'd expect.
We would love to help you with adopting Pants. Please reach out through Slack.
Follow the Getting Started guide to install Pants and set up an initial
pants.toml. Validate that running
./pants count-loc '**' works properly.
backend_packages = ["pants.backend.python"] to the
Formatters and linters are often the simplest to get working because—for all tools other than Pylint— you do not need to worry about things like dependencies and third-party requirements.
First, create a BUILD file in each directory with Python code. As explained in Targets and BUILD files, you can use fewer BUILD files, such as one BUILD file per subproject; but we find that one BUILD file per directory is a good default.
./pants tailorto cut down on manual work
tailorgoal will generate initial BUILD files for you! You may need to tweak them manually, but for the most part the auto-generated ones should get you off to a good start. You can run
./pants tailoragain as you add new files in the future.
If your directory only contains production code, use
If your directory only contains tests, use
If your directory contains both production code and tests, use both:
Unless you want to change the default values, such as setting timeouts for your tests, you can simply use these 1-3 lines in each BUILD file.
Pants's dependency inference will infer most dependencies for you by looking at your Python import statements. Generally, you will not need to update your BUILD files any more than the previous step.
However, if your tests depend on any resource files, you will need to explicitly declare these dependencies because Pants cannot infer them. See Resources.
./pants test :: in CI to see if any tests fail. Sometimes, your tests will fail with Pants even if they pass with your normal setup because tests are more isolated than when running Pytest/unittest directly:
- Tests run in a chroot, meaning they can only access dependencies that Pants knows about. If you have a missing file or missing import, run
./pants dependencies path/to/my_test.pyand
./pants dependencies --transitive path/to/my_test.pyto confirm what you are expecting is known by Pants. If not, add to the
- Test files are isolated from each other. If your tests depended on running in a certain order, they may now fail. This requires rewriting your tests to remove the shared global state.
In your CI, you may want to speed up your build by having Pants only run tests for changed files. Refer to Using Pants in CI.
We recommend manually verifying that this step is working how you'd like by inspecting the built packages. Alternatively, you can write automated tests that will call the equivalent of
./pants package for you, and insert the built package into your test environment.
Pants is highly extensible. In fact, all of Pants's core functionality is implemented using the exact same API used by plugins.
Some example plugins that users have written:
- Cython support
- Building a Docker image with packages built via
setup.pylogic to compute the
- Jupyter support
If you're migrating from another build tool that already uses the name
BUILD, such as Bazel or Please, you can tell Pants to use a different file name than
BUILD to avoid conflicts:
[GLOBAL] build_patterns = ["BUILD.pants"]
Alternatively, you can tell Pants to not look for BUILD files in certain locations. This can be helpful, for example, if you use a tool like Bazel for Java, but use Pants for Python:
[GLOBAL] build_ignore = ["src/java"]
Updated about a month ago