Version: 2.23 (prerelease)

python

Options for Pants's Python backend.

Backend: pants.backend.python.lint.isort

Config section: [python]

Basic options

`default_run_goal_use_sandbox`

--[no-]python-default-run-goal-use-sandbox
PANTS_PYTHON_DEFAULT_RUN_GOAL_USE_SANDBOX

pants.toml
[python]
default_run_goal_use_sandbox = <bool>

default: True

The default value used for the run_goal_use_sandbox field of Python targets. See the relevant field for more details.

`repl_history`

--[no-]python-repl-history
PANTS_PYTHON_REPL_HISTORY

pants.toml
[python]
repl_history = <bool>

default: True

Whether to use the standard Python command history file when running a repl.

Advanced options

`default_resolve`

--python-default-resolve=<str>
PANTS_PYTHON_DEFAULT_RESOLVE

pants.toml
[python]
default_resolve = <str>

default: python-default

The default value used for the resolve field.

The name must be defined as a resolve in [python].resolves.

`enable_lockfile_targets`

--[no-]python-enable-lockfile-targets
PANTS_PYTHON_ENABLE_LOCKFILE_TARGETS

pants.toml
[python]
enable_lockfile_targets = <bool>

default: True

Create targets for all Python lockfiles defined in [python].resolves.

The lockfile targets will then be used as dependencies to the python_requirement targets that use them, invalidating source targets per resolve when the lockfile changes.

If another targets address is in conflict with the created lockfile target, it will shadow the lockfile target and it will not be available as a dependency for any python_requirement targets.

`enable_resolves`

--[no-]python-enable-resolves
PANTS_PYTHON_ENABLE_RESOLVES

pants.toml
[python]
enable_resolves = <bool>

default: False

Set to true to enable lockfiles for user code. See [python].resolves for an explanation of this feature.

This option is mutually exclusive with [python].requirement_constraints. We strongly recommend using this option because it:

Uses --hash to validate that all downloaded files are expected, which reduces the risk of supply chain attacks.
Enforces that all transitive dependencies are in the lockfile, whereas constraints allow you to leave off dependencies. This ensures your build is more stable and reduces the risk of supply chain attacks.
Allows you to have multiple lockfiles in your repository.

`interpreter_constraints`

--python-interpreter-constraints="[<requirement>, <requirement>, ...]"
PANTS_PYTHON_INTERPRETER_CONSTRAINTS

pants.toml
[python]
interpreter_constraints = [
    <requirement>,
    <requirement>,
    ...,
]

default: []

The Python interpreters your codebase is compatible with.

These constraints are used as the default value for the interpreter_constraints field of Python targets.

Specify with requirement syntax, e.g. 'CPython>=2.7,<3' (A CPython interpreter with version >=2.7 AND version <3) or 'PyPy' (A pypy interpreter of any version). Multiple constraint strings will be ORed together.

`interpreter_versions_universe`

--python-interpreter-versions-universe="['<str>', '<str>', ...]"
PANTS_PYTHON_INTERPRETER_VERSIONS_UNIVERSE

pants.toml
[python]
interpreter_versions_universe = [
    '<str>',
    '<str>',
    ...,
]

default:

[
  "2.7",
  "3.5",
  "3.6",
  "3.7",
  "3.8",
  "3.9",
  "3.10",
  "3.11",
  "3.12",
  "3.13"
]

All known Python major/minor interpreter versions that may be used by either your code or tools used by your code.

This is used by Pants to robustly handle interpreter constraints, such as knowing when generating lockfiles which Python versions to check if your code is using.

This does not control which interpreter your code will use. Instead, to set your interpreter constraints, update [python].interpreter_constraints, the interpreter_constraints field, and relevant tool options like [isort].interpreter_constraints to tell Pants which interpreters your code actually uses. See https://www.pantsbuild.org/2.23/docs/python/overview/interpreter-compatibility.

All elements must be the minor and major Python version, e.g. '2.7' or '3.10'. Do not include the patch version.

`invalid_lockfile_behavior`

--python-invalid-lockfile-behavior=<InvalidLockfileBehavior>
PANTS_PYTHON_INVALID_LOCKFILE_BEHAVIOR

pants.toml
[python]
invalid_lockfile_behavior = <InvalidLockfileBehavior>

one of: error, ignore, warn
default: error

The behavior when a lockfile has requirements or interpreter constraints that are not compatible with what the current build is using.

We recommend keeping the default of error for CI builds.

Note that warn will still expect a Pants lockfile header, it only won't error if the lockfile is stale and should be regenerated.

Use ignore to avoid needing a lockfile header at all, e.g. if you are manually managing lockfiles rather than using the generate-lockfiles goal.

`macos_big_sur_compatibility`

--[no-]python-macos-big-sur-compatibility
PANTS_PYTHON_MACOS_BIG_SUR_COMPATIBILITY

pants.toml
[python]
macos_big_sur_compatibility = <bool>

default: False

If set, and if running on macOS Big Sur, use macosx_10_16 as the platform when building wheels. Otherwise, the default of macosx_11_0 will be used. This may be required for pip to be able to install the resulting distribution on Big Sur.

`pip_version`

--python-pip-version=<str>
PANTS_PYTHON_PIP_VERSION

pants.toml
[python]
pip_version = <str>

default: 24.0

Use this version of Pip for resolving requirements and generating lockfiles.

The value used here must be one of the Pip versions supported by the underlying PEX version. See https://www.pantsbuild.org/2.23/docs/python/overview/pex for details.

N.B.: The latest value selects the latest of the choices listed by PEX which is not necessarily the latest Pip version released on PyPI.

`resolver_manylinux`

--python-resolver-manylinux=<str>
PANTS_PYTHON_RESOLVER_MANYLINUX

pants.toml
[python]
resolver_manylinux = <str>

default: manylinux2014

Whether to allow resolution of manylinux wheels when resolving requirements for foreign linux platforms. The value should be a manylinux platform upper bound, e.g. 'manylinux2010', or else the string 'no' to disallow.

`resolves`

--python-resolves="{'key1': val1, 'key2': val2, ...}"
PANTS_PYTHON_RESOLVES

pants.toml
[python.resolves]
key1 = val1
key2 = val2
...

default:

{
  "python-default": "3rdparty/python/default.lock"
}

A mapping of logical names to lockfile paths used in your project.

Many organizations only need a single resolve for their whole project, which is a good default and often the simplest thing to do. However, you may need multiple resolves, such as if you use two conflicting versions of a requirement in your repository.

If you only need a single resolve, run pants generate-lockfiles to generate the lockfile.

If you need multiple resolves:

Via this option, define multiple resolve names and their lockfile paths. The names should be meaningful to your repository, such as data-science or pants-plugins.
Set the default with [python].default_resolve.
Update your python_requirement targets with the resolve field to declare which resolve they should be available in. They default to [python].default_resolve, so you only need to update targets that you want in non-default resolves. (Often you'll set this via the python_requirements or poetry_requirements target generators)
Run pants generate-lockfiles to generate the lockfiles. If the results aren't what you'd expect, adjust the prior step.
Update any targets like python_source / python_sources, python_test / python_tests, and pex_binary which need to set a non-default resolve with the resolve field.

If a target can work with multiple resolves, you can either use the parametrize mechanism or manually create a distinct target per resolve. See https://www.pantsbuild.org/2.23/docs/using-pants/key-concepts/targets-and-build-files for information about parametrize.

For example:

python_sources(
    resolve=parametrize("data-science", "web-app"),
)

You can name the lockfile paths what you would like; Pants does not expect a certain file extension or location.

Only applies if [python].enable_resolves is true.

`resolves_generate_lockfiles`

--[no-]python-resolves-generate-lockfiles
PANTS_PYTHON_RESOLVES_GENERATE_LOCKFILES

pants.toml
[python]
resolves_generate_lockfiles = <bool>

default: True

If False, Pants will not attempt to generate lockfiles for [python].resolves when running the generate-lockfiles goal.

This is intended to allow you to manually generate lockfiles for your own code, rather than using Pex lockfiles. For example, when adopting Pants in a project already using Poetry, you can use poetry export --dev to create a requirements.txt-style lockfile understood by Pants, then point [python].resolves to the file.

If you set this to False, Pants will not attempt to validate the metadata headers for your user lockfiles. This is useful so that you can keep [python].invalid_lockfile_behavior to error or warn if you'd like so that tool lockfiles continue to be validated, while user lockfiles are skipped.

Warning: it will likely be slower to install manually generated user lockfiles than Pex ones because Pants cannot as efficiently extract the subset of requirements used for a particular task. See the option [python].run_against_entire_lockfile.

`resolves_to_constraints_file`

--python-resolves-to-constraints-file="{'key1': val1, 'key2': val2, ...}"
PANTS_PYTHON_RESOLVES_TO_CONSTRAINTS_FILE

pants.toml
[python.resolves_to_constraints_file]
key1 = val1
key2 = val2
...

default: {}

When generating a resolve's lockfile, use a constraints file to pin the version of certain requirements. This is particularly useful to pin the versions of transitive dependencies of your direct requirements.

See https://pip.pypa.io/en/stable/user_guide/#constraints-files for more information on the format of constraint files and how constraints are applied in Pex and pip.

Expects a dictionary of resolve names from [python].resolves and Python tools (e.g. black and pytest) to file paths for constraints files. For example, {'data-science': '3rdparty/data-science-constraints.txt'}. If a resolve is not set in the dictionary, it will not use a constraints file.

You can use the key __default__ to set a default value for all resolves.

`resolves_to_interpreter_constraints`

--python-resolves-to-interpreter-constraints="{'key1': val1, 'key2': val2, ...}"
PANTS_PYTHON_RESOLVES_TO_INTERPRETER_CONSTRAINTS

pants.toml
[python.resolves_to_interpreter_constraints]
key1 = val1
key2 = val2
...

default: {}

Override the interpreter constraints to use when generating a resolve's lockfile with the generate-lockfiles goal.

By default, each resolve from [python].resolves will use your global interpreter constraints set in [python].interpreter_constraints. With this option, you can override each resolve to use certain interpreter constraints, such as {'data-science': ['==3.8.*']}.

Warning: this does NOT impact the interpreter constraints used by targets within the resolve, which is instead set by the option [python].interpreter_constraints and the interpreter_constraints field. It only impacts how the lockfile is generated.

Pants will validate that the interpreter constraints of your code using a resolve are compatible with that resolve's own constraints. For example, if your code is set to use ['==3.9.*'] via the interpreter_constraints field, but it's using a resolve whose interpreter constraints are set to ['==3.7.*'], then Pants will error explaining the incompatibility.

The keys must be defined as resolves in [python].resolves.

`resolves_to_no_binary`

--python-resolves-to-no-binary="{'key1': val1, 'key2': val2, ...}"
PANTS_PYTHON_RESOLVES_TO_NO_BINARY

pants.toml
[python.resolves_to_no_binary]
key1 = val1
key2 = val2
...

default: {}

When generating a resolve's lockfile, do not use binary packages (i.e. wheels) for these 3rdparty project names.

Expects a dictionary of resolve names from [python].resolves and Python tools (e.g. black and pytest) to lists of project names. For example, {'data-science': ['requests', 'numpy']}. If a resolve is not set in the dictionary, it will have no restrictions on binary packages.

You can use the key __default__ to set a default value for all resolves.

For each resolve, you can also use the value :all: to disable all binary packages: {'data-science': [':all:']}.

Note that some packages are tricky to compile and may fail to install when this option is used on them. See https://pip.pypa.io/en/stable/cli/pip_install/#install-no-binary for details.

`resolves_to_only_binary`

--python-resolves-to-only-binary="{'key1': val1, 'key2': val2, ...}"
PANTS_PYTHON_RESOLVES_TO_ONLY_BINARY

pants.toml
[python.resolves_to_only_binary]
key1 = val1
key2 = val2
...

default: {}

When generating a resolve's lockfile, do not use source packages (i.e. sdists) for these 3rdparty project names, e.g ['django', 'requests'].

You can use the key __default__ to set a default value for all resolves.

For each resolve you can use the value :all: to disable all source packages: {'data-science': [':all:']}.

Packages without binary distributions will fail to install when this option is used on them. See https://pip.pypa.io/en/stable/cli/pip_install/#install-only-binary for details.

`run_against_entire_lockfile`

--[no-]python-run-against-entire-lockfile
PANTS_PYTHON_RUN_AGAINST_ENTIRE_LOCKFILE

pants.toml
[python]
run_against_entire_lockfile = <bool>

default: False

If enabled, when running binaries, tests, and repls, Pants will use the entire lockfile file instead of just the relevant subset.

If you are using Pex lockfiles, we generally do not recommend this. You will already get similar performance benefits to this option, without the downsides.

Otherwise, this option can improve performance and reduce cache size. But it has two consequences: 1) All cached test results will be invalidated if any requirement in the lockfile changes, rather than just those that depend on the changed requirement. 2) Requirements unneeded by a test/run/repl will be present on the sys.path, which might in rare cases cause their behavior to change.

This option does not affect packaging deployable artifacts, such as PEX files, wheels and cloud functions, which will still use just the exact subset of requirements needed.

`tailor_ignore_empty_init_files`

--[no-]python-tailor-ignore-empty-init-files
PANTS_PYTHON_TAILOR_IGNORE_EMPTY_INIT_FILES

pants.toml
[python]
tailor_ignore_empty_init_files = <bool>

default: True

If true, don't add python_sources targets for __init__.py files that are both empty and where there are no other Python files in the directory.

Empty and solitary __init__.py files usually exist as import scaffolding rather than true library code, so it can be noisy to add BUILD files.

Even if this option is set to true, Pants will still ensure the empty __init__.py files are included in the sandbox when running processes.

If you set to false, you may also want to set [python-infer].init_files = "always".

`tailor_pex_binary_targets`

--[no-]python-tailor-pex-binary-targets
PANTS_PYTHON_TAILOR_PEX_BINARY_TARGETS

pants.toml
[python]
tailor_pex_binary_targets = <bool>

default: False

If true, add pex_binary targets for Python files named __main__.py or with a __main__ clause with the tailor goal.

`tailor_py_typed_targets`

--[no-]python-tailor-py-typed-targets
PANTS_PYTHON_TAILOR_PY_TYPED_TARGETS

pants.toml
[python]
tailor_py_typed_targets = <bool>

default: True

If true, add resource targets for marker files named py.typed with the tailor goal.

`tailor_requirements_targets`

--[no-]python-tailor-requirements-targets
PANTS_PYTHON_TAILOR_REQUIREMENTS_TARGETS

pants.toml
[python]
tailor_requirements_targets = <bool>

default: True

If true, add python_requirements, poetry_requirements, and pipenv_requirements target generators with the tailor goal.

python_requirements targets are added for any file that matches the pattern *requirements*.txt. You will need to manually add python_requirements for different file names like reqs.txt.

poetry_requirements targets are added for pyproject.toml files with [tool.poetry in them.

`tailor_source_targets`

--[no-]python-tailor-source-targets
PANTS_PYTHON_TAILOR_SOURCE_TARGETS

pants.toml
[python]
tailor_source_targets = <bool>

default: True

If true, add python_sources, python_tests, and python_test_utils targets with the tailor goal.

`warn_on_python2_usage`

--[no-]python-warn-on-python2-usage
PANTS_PYTHON_WARN_ON_PYTHON2_USAGE

pants.toml
[python]
warn_on_python2_usage = <bool>

default: True

True if Pants should generate a deprecation warning when Python 2.x is used in interpreter constraints.

As of Pants v2.24.x and later, Pants will no longer be tested regularly with Python 2.7.x. As such, going forward, Pants may or may not work with Python 2.7. This option allows disabling the deprecation warning announcing this policy change.

Deprecated options

`requirement_constraints`

--python-requirement-constraints=<file_option>
PANTS_PYTHON_REQUIREMENT_CONSTRAINTS

pants.toml
[python]
requirement_constraints = <file_option>

default: None
Deprecated, will be removed in version: 3.0.0.dev0.
We encourage instead migrating to `[python].enable_resolves` and `[python].resolves`, which is an improvement over this option. The `[python].resolves` feature ensures that your lockfiles are fully comprehensive, i.e. include all transitive dependencies; uses hashes for better supply chain security; and supports advanced features like VCS and local requirements, along with options `[python].resolves_to_only_binary`.<br /><br />To migrate, stop setting `[python].requirement_constraints` and `[python].resolve_all_constraints`, and instead set `[python].enable_resolves` to `true`. Then, run `pants generate-lockfiles`.

When resolving third-party requirements for your own code (vs. tools you run), use this constraints file to determine which versions to use.

Mutually exclusive with [python].enable_resolves, which we generally recommend as an improvement over constraints file.

See https://pip.pypa.io/en/stable/user_guide/#constraints-files for more information on the format of constraint files and how constraints are applied in Pex and pip.

This only applies when resolving user requirements, rather than tools you run like Black and Pytest. To constrain tools, set [tool].lockfile, e.g. [black].lockfile.

`resolve_all_constraints`

--[no-]python-resolve-all-constraints
PANTS_PYTHON_RESOLVE_ALL_CONSTRAINTS

pants.toml
[python]
resolve_all_constraints = <bool>

default: True
Deprecated, will be removed in version: 3.0.0.dev0.
We encourage instead migrating to `[python].enable_resolves` and `[python].resolves`, which is an improvement over this option. The `[python].resolves` feature ensures that your lockfiles are fully comprehensive, i.e. include all transitive dependencies; uses hashes for better supply chain security; and supports advanced features like VCS and local requirements, along with options `[python].resolves_to_only_binary`.<br /><br />To migrate, stop setting `[python].requirement_constraints` and `[python].resolve_all_constraints`, and instead set `[python].enable_resolves` to `true`. Then, run `pants generate-lockfiles`.

(Only relevant when using [python].requirement_constraints.) If enabled, when resolving requirements, Pants will first resolve your entire constraints file as a single global resolve. Then, if the code uses a subset of your constraints file, Pants will extract the relevant requirements from that global resolve so that only what's actually needed gets used. If disabled, Pants will not use a global resolve and will resolve each subset of your requirements independently.

Usually this option should be enabled because it can result in far fewer resolves.

None

Basic options​

default_run_goal_use_sandbox​

repl_history​

Advanced options​

default_resolve​

enable_lockfile_targets​

enable_resolves​

interpreter_constraints​

interpreter_versions_universe​

invalid_lockfile_behavior​

macos_big_sur_compatibility​

pip_version​

resolver_manylinux​

resolves​

resolves_generate_lockfiles​

resolves_to_constraints_file​

resolves_to_interpreter_constraints​

resolves_to_no_binary​

resolves_to_only_binary​

run_against_entire_lockfile​

tailor_ignore_empty_init_files​

tailor_pex_binary_targets​

tailor_py_typed_targets​

tailor_requirements_targets​

tailor_source_targets​

warn_on_python2_usage​

Deprecated options​

requirement_constraints​

resolve_all_constraints​

Related subsystems​

Basic options

`default_run_goal_use_sandbox`

`repl_history`

Advanced options

`default_resolve`

`enable_lockfile_targets`

`enable_resolves`

`interpreter_constraints`

`interpreter_versions_universe`

`invalid_lockfile_behavior`

`macos_big_sur_compatibility`

`pip_version`

`resolver_manylinux`

`resolves`

`resolves_generate_lockfiles`

`resolves_to_constraints_file`

`resolves_to_interpreter_constraints`

`resolves_to_no_binary`

`resolves_to_only_binary`

`run_against_entire_lockfile`

`tailor_ignore_empty_init_files`

`tailor_pex_binary_targets`

`tailor_py_typed_targets`

`tailor_requirements_targets`

`tailor_source_targets`

`warn_on_python2_usage`

Deprecated options

`requirement_constraints`

`resolve_all_constraints`

Related subsystems