Pants v2: The ergonomic build system

Welcome to the Pants v2 documentation hub!

Pants v2 is a fast, scalable, user-friendly build system for growing codebases. It's currently focused on Python, with support for other languages coming soon.

Here you'll find guides to help you get started with Pants v2, comprehensive documentation on how to configure, run and customize Pants v2, and information on how to get help from the Pants community.

Get Started


Open a REPL for interactive development.

Pants will load a REPL with all of your specified source code and any of its third-party dependencies, which allows you to import those values.


In addition to the default Python shell, Pants supports the improved IPython shell.

To use IPython, run ./pants repl --shell=ipython. To permanently use IPython, add this to your pants.toml:

shell = "ipython"

You can change IPython's version with --ipython-version:

version = "ipython>=6.0.0"

If you set the version lower than IPython 7, then you must set ignore_cwd = false in the [ipython] section to avoid Pants setting an option that did not exist in earlier IPython releases.


IPython does not yet work with Pantsd

When using IPython, use the option --no-pantsd to turn off the Pants daemon, e.g. ./pants --no-pantsd repl --shell=ipython. We are working to fix this.


Python 2 support

Pants uses IPython 7 by default, which does not work with Python 2. You can override version to use IPython 5. As mentioned above, you must set ignore_cwd = false.

version = "ipython<6"
ignore_cwd = false

You can even use IPython 7 for Python 3 code, and IPython 5 for Python 2 code:

version = "ipython==7.16.1 ; python_version >= '3.6'"
extra_requirements.add = ["ipython<6 ; python_version == '2.7'"]
ignore_cwd = false


$ ./pants repl helloworld/greet/

Python 3.7.6 (default, Feb 26 2020, 08:28:08)
[Clang 11.0.0 (clang-1100.0.33.8)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from helloworld.greet.greeting import Greeter
>>> Greeter().greet("Pants")
'buenas tardes, Pants!'
>>> from translate import Translator
>>> Translator(to_lang="fr").translate("Good morning.")

This will not load any of your code:

$ ./pants --no-pantsd repl --shell=ipython

Python 3.6.10 (default, Feb 26 2020, 08:26:13)
Type "copyright", "credits" or "license" for more information.

IPython 5.8.0 -- An enhanced Interactive Python.
?         -> Introduction and overview of IPython's features.
%quickref -> Quick reference.
help      -> Python's own help system.
object?   -> Details about 'object', use 'object??' for extra details.

In [1]: 21 * 4
Out[1]: 84


Tip: how to exit the REPL

Either type exit() and hit enter, or press ctrl+d.

Updated 6 months ago


Open a REPL for interactive development.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.