## Recommended steps

If you have an existing repository, we recommend incrementally adopting to reduce the surface area of change, which reduces risk.

Incremental adoption also allows you to immediately start benefitting from Pants, then deepen adoption at your own pace, instead of postponing benefit until you are ready to make dramatic change all at once.

📘

Joining Slack

We would love to help you with adopting Pants. Please reach out through [Slack](🔗).

### 1. A basic `pants.toml`

Follow the [Getting Started](🔗) guide to install Pants and [set up an initial `pants.toml`](🔗). Validate that running `./pants count-loc '**'` works properly. If you want to exclude a specific folder at first, you can use the [`pants_ignore`](🔗) option.

Add the [relevant backends](🔗) to `[GLOBAL].backend_packages`.

### 2. Set up formatters/linters with basic BUILD files

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, run [`./pants tailor`](🔗) to generate BUILD files. This tells Pants which files to operate on, and will allow you to set additional metadata over time like test timeouts and dependencies on resources.

Then, activate the [Linters and formatters](🔗) you'd like to use. Hook up the `fmt` and `lint` goals to your [CI](🔗).

### 3. Set up tests

To get [tests](🔗) working, you will first need to set up [source roots](🔗) and [third-party dependencies](🔗).

Pants's [dependency inference](🔗) will infer most dependencies for you by looking at your import statements. However, some dependencies cannot be inferred, such as [resources](🔗).

Try running `./pants test ::` 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 sandbox, 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.py` and `./pants dependencies --transitive path/to/my_test.py` to confirm what you are expecting is known by Pants. If not, see [Troubleshooting / common issues](🔗) for reasons dependency inference can fail.

• 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.

You can port your tests incrementally with the `skip_tests` field:

`./pants test ::` will only run the relevant tests. You can combine this with [`./pants peek`](🔗) to get a list of test files that should be run with your original test runner:

You may want to [speed up your CI](🔗) by having Pants only run tests for changed files.

### 4. Set up `./pants package`

You can use `./pants package` to package your code into various formats, such as a [PEX binary](🔗), a [wheel](🔗), an [AWS Lambda](🔗), or a [zip/tar archive](🔗).

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.

### 5. Check out writing a plugin

Pants is highly extensible. In fact, all of Pants's core functionality is implemented using the exact same API used by plugins.

Check out [Plugins Overview](🔗). We'd also love to help in the #plugins channel on [Slack](🔗).

Some example plugins that users have written:

• Cython support

• Building a Docker image with packages built via `./pants package`

• Custom `setup.py` logic to compute the `version` dynamically

• Jupyter support

## Migrating from other BUILD tools? Set custom BUILD file names

If you're migrating from another system that already uses the name `BUILD`, such as Bazel or Please, you have a few ways to avoid conflicts:

First, by default Pants recognizes `BUILD.extension` for any `extension` as a valid BUILD file. So you can use a name like `BUILD.pants` without changing configuration.

Second, you can [configure](🔗) Pants to use a different set of file names entirely:

And finally you can configure Pants to not look for BUILD files in certain locations. This can be helpful, for example, if you use Pants for some languages and another tool for other languages: