Skip to main content
Version: 2.22

Enabling Python support

How to enable Pants's bundled Python backend package.

Example Python repository

See here for examples of Pants's Python functionality.

See here for Django-specific examples.

Enable the Python backend like this:

pants.toml
[GLOBAL]
...
backend_packages = [
  "pants.backend.python"
]

Pants use python_source and python_test targets to know which Python files to run on and to set any metadata.

To reduce boilerplate, the python_sources target generates a python_source target for each file in its sources field, and python_tests generates a python_test target for each file in its sources field.

BUILD
python_sources(name="lib", sources=["dirutil.py", "strutil.py"])
python_tests(name="tests", sources=["strutil_test.py"])

# Spiritually equivalent to:
python_source(name="dirutil", source="dirutil.py")
python_source(name="strutil", source="strutil.py")
python_test(name="strutil_test.py", source="strutil_test.py")

# Thanks to the default `sources` values, spiritually equivalent to:
python_sources(name="lib")
python_tests(name="tests")

You can generate these targets by running pants tailor ::.

❯ pants tailor ::
Created project/BUILD:
  - Add python_sources target project
  - Add python_tests target tests
macOS users: you may need to change interpreter search paths

By default, Pants will look at both your $PATH and—if you use Pyenv—your $(pyenv root)/versions folder when discovering Python interpreters. Your $PATH likely includes the system Pythons at /usr/bin/python and /usr/bin/python3, which are known to have many issues like failing to install some dependencies.

Pants will prefer new Python versions, like 3.6.10 over 3.6.3. Because macOS system Pythons are usually very old, they will usually be ignored.

However, if you run into issues, you can set the search_paths option in the [python-bootstrap] scope:

[python-bootstrap]
search_path = [
    # This will use all interpreters in `$(pyenv root)/versions`.
    "<PYENV>",
     # Brew usually installs Python here.
    "/usr/local/bin",
]

See here for more information.