2.20.x.md

2.20.x Release Series

Pants 2 is a fast, scalable, user-friendly build system for codebases of all sizes. It's currently focused on Python, Go, Java, Scala, Kotlin, Shell, and Docker, with support for other languages and frameworks coming soon.

Individuals and companies can now sponsor Pants financially.

Pants is an open-source project that is not owned or controlled by any one company or organization, and does incur some expenses. These expenses are managed by Pants Build, a non-profit that was established for this purpose. This non-profit's only source of revenue is sponsorship by individuals and companies that use Pants.

We offer formal sponsorship tiers for companies, as well as individual sponsorships via GitHub.

What's New

Highlights

• Support for the Ruff formatter, for both BUILD files and normal Python files.
• Built-in support for Terraform lockfiles.
• Support for more remote-caching providers: file system and GitHub Actions Cache.
• New helpers for defining "adhoc" code-quality tools, without requiring a full plugin.
• JVM third-party artifacts can now be read from pom.xml files, and other related improvements.
• Go 1.22 can now be used.

Keep reading to see the details and what's also included.

Overall

The dependency goals now support JSON output using the --format option for easier introspection of the dependency graph. For instance, pants dependencies --format=json ... and pants dependents --format=json ....

The new [stats].output_file option allows appending the stats output to a file, rather than printing it on stdout. This allows hiding this output on CI, while still ensuring it's available when required.

The [GLOBAL].pants_ignore option no longer ignores .github by default, so files within that directory will now be visible to Pants automatically.

Using the --changed-... options to only run on files that have been edited now no longer emits spurious warnings if files have been deleted.

We've made many changes to documentation, including:

• How to use the .pants.bootstrap file for running commands before start-up or setting default environment variables or similar.
• How to use the [cli].alias option for abbreviating common pants invocations.
• How to use the target target to abbreviate common dependencies=["..."] parameters.
• An improved version of the nuking script when doing coarse-grained caching in CI, like GitHub Actions.
• Several pages have been renamed or moved: existing links to 2.19 and earlier will still work, but their locations in 2.20 may have changed.

BUILD files

The new pants.backend.build_files.fmt.ruff backend allows using the Ruff formatter to format BUILD files.

Remote caching/execution

Pants now has experimental support for additional remote cache providers beyond the gRPC Remote Execution API. Set the [GLOBAL].remote_provider option, to be able to use:

• the GitHub Actions Cache
• a local directory

In support of this, the [GLOBAL].remote_oauth_bearer_token option has been added to set the Authorization: Bearer <token> header. The [GLOBAL].remote_oauth_bearer_token_path option has been deprecated in favour of using the new option with a file reference: remote_oauth_bearer_token = "@/path/to/file.txt".

The [GLOBAL].remote_cache_warnings option now supports always.

Backends

Adhoc

The new code_quality_tool target in the pants.backend.experimental.adhoc backend allows defining "adhoc" linters, formatters and fixers without requiring a full plugin. For example, in-repository scripts or a tool not already supported by Pants itself. See #20135 for an example of how to use this.

Docker

The new {full_directory} interpolation in repository and default_repository options expands to the full path to the BUILD file that contains a docker_image target.

The new pants.backend.experimental.docker.podman backend allows using Podman. Add that backend to backend_packages and the Docker backend will invoke Podman instead of Docker. The new option [docker].experimental_enable_podman allows disabling this once the backend is loaded.

Dependency inference now works for parameterized targets, like ARG base="path/to:target@param=value".

Pants is now able to extract the image ID when building a docker image with a daemon using the containerd-snapshotter feature.

The default version of Hadolint has been updated from 2.10.0 to 2.12.1-beta. This fixes an segmentation fault error when running on MacOS.

Go

Support for Go 1.22+, by no longer passing the -compiling-runtime flag when not necessary.

Eliminated a non-linear blow-up in the algorthm for gathering pre-build Go object files when using CGo.

Helm

The new lint_quiet field on helm_chart allows passing --quiet to helm lint ....

The repository field on helm_chart now allows trailing slashes.

The --timeout flag can now be passed through to helm upgrade operations.

JavaScript

The pants.backend.experimental.javascript experimental backend has had a few bug-fixes:

• package_json targets that use yarn now support running node_build_scripts.
• Dependencies are inferred from export ... from ... statements, similar to import ... from ....

JVM

Several improvements have been made to Pants' support for third-party dependencies:

• The new jvm_artifacts target supports creating jvm_artifact dependency targets from pom.xml files.
• The new force_version field on jvm_artifact allows passing the --force-version flag to Coursier for particular artifacts.
• The new [coursier].jvm_index option allows setting the index used by Coursier.

Most codegen backends now support dependency inference, including Protobuf, SOAP, Thrift and OpenAPI.

Pants support for IDE integration via the BSP protocol now supports Scala plugins.

The JVM documentation has been rearranged to put Java and Scala and Kotlin on an equal footing.

Scala

Plugins that cause scalac to emit additional compilation results (such as semanticdb, scalajs and scalanative) are now supported, by wrapping all results into a single jar.

Support for the Scala REPL is now documented.

Python

Several improvements have been made to Pants' support for Ruff:

• The new pants.backend.experimental.python.lint.ruff.format backend allows using the Ruff formatter to format Python files.
• The existing pants.backend.experimental.python.lint.ruff linter backend has been renamed to pants.backend.experimental.python.lint.ruff.check, and its tool ID (as used by commands like pants lint --only=...) has changed from ruff to ruff-check.
• Pants now automatically finds Ruff configuration in pyproject.toml files in subdirectories, for instance, python/pyproject.toml.
• Pants' built-in default version has been updated to 0.2.1.

This release brings several changes related to the pex tool and pex_binary targets:

• It has been updated to to 2.1.163 by default. The minimum supported version is now 2.1.148.
• The new sh_boot field allows opting in to using a shell script rather than a Python script, which can be faster and more reliable in some cases.
• The new executable field on pex_binary targets exposes pex's --executable option.
• The new [pex].emit_warnings option allows controlling whether warnings from pex invocations are shown or not.
• The existing emit_warnings field on pex_binary targets now works as described, when set to True.
• Relatedly, Pants now exposes the recently-added --check option that allows being warned in advance if a pex_binary target will not be able to be opened by CPython. The new check field allows adjusting the behaviour (default: warn).
• If a pex_binary has an entry_point field that is ambiguous, Pants now treats this as an unowned dependency. Previously this would silently do nothing.

The new local_scheme and version_scheme fields on the vcs_version target allow additional customization of its behaviour.

Improvements to dependency inference:

• Strings imports are handled more reliably, including obeying pants: no-infer-dep comments and having fewer false positives on invalid module names.
• Django-specific dependency inference (via the pants.backend.experimental.python.framework.django backend) now infers migrations and management commands as dependencies of apps.py.

The pants.backend.codegen.protobuf.python backend now supports using grpclib in addition to grpcio for generating GRPC service stubs.

Default module mappings were added for more modules: django-countries, django-fsm, django-object-actions, django-postgres-extra, django-redis, django-scim2, djangorestframework-api-key, djangorestframework-queryfields, google-api-python-client, google-auth, grpcio-health-checking, grpcio-reflection, honeycomb-opentelemetry, opencv-python-headless, opentelemetry-sdk (expanded to cover more modules). The special _typeshed module no longer has errors if imported.

pip list now behaves correctly in venvs created via export with the [export].py_editable_in_resolve option enabled.

There is now documentation on how to exclude files from Black or isort.

The deprecation for the [export].symlink_python_virtualenv option has expired and it has been removed. Instead set the [export].py_resolve_format option to symlinked_immutable_virtualenv.

Terraform

The pants.backend.experimental.terraform Terraform backend now has built-in support for lockfiles, using the pants generate-lockfiles --resolve=path/to:module goal, passing the address of the terraform_module target as the resolve.

There are now separate target types for vars files and backend configs, which are handled as normal dependencies in the dependencies field. See the new instructions for Terraform deployments.

The default built-in version of Terraform has been upgraded from 1.4.6 to 1.7.1. Pants now has built-in knowledge of versions up to 1.7.1, so the version can be overridden by setting [download-terraform].version explicitly.

NEW: TypeScript

The pants.backend.experimental.typescript experimental backend now exists with support for tailoring typescript_sources and typescript_tests targets. Note: dependency inference and other built-in functionality is not yet implemented.

Plugin API changes

Pants is undergoing a long term project to switch to a new "call by name" syntax. There will be a "fix-up" tool once the new syntax is ready for wide-spread use. This release adds supports for positional arguments. (#20366)

AbstractLintRequest subclasses can now disable lint rules via the enable_lint_rules class var, if the automatic linter is not required. (#20407)

Plugins loaded from the current repository (by extending [GLOBAL].pythonpath) now support specifying their requirements in a requirements.txt file adjacent to register.py. (#20355)

FrozenDicts comparison and hashing functions now behave more like the superclass dict ones, being order-insensitive and allowing comparison to dict itself. (#20221)

Previously, backtraces have been improved, to lose less information when interacting with the Rust core code. (#20517)

The documentation has been extended with more information and additional examples:

• how to use HydratedSources to convert a list of file and target paths into just file paths (#20524)
• how to write an integration test that requires loading a backend (#20451)
• how to write a unit test for a @rule (#20452)
• how to profile Pants with py-spy and memray (#20334)

The deprecation has expired for the @rule_helper decorator. To resolve, just remove it: @rules can now call any functions and async functions can now call Get and MultiGet directly.

Full Changelog

For the full changelog, see the individual GitHub Releases for this series: https://github.com/pantsbuild/pants/releases