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.
- Pants now has its first sponsors! We are very grateful to Klayvio and Normal Computing for their Platinum tier support, and to Continua and Stormfish for their Silver tier support.
- New backend for the buildifier BUILD file formatter.
- Two new experimental backends: nFPM and Trufflehog. Try them out and let us know how it goes!
- Better dependency inference for Dockerfiles.
- Improvements to platform handling in Python function-as-a-service targets.
- Enhancements to Terraform lockfiles and caching.
And many more changes!
-
macOS: Running Pants on macOS 10.15 or macOS 11 has been deprecated. Future versions will only support running on macOS 12 or newer. If you have questions or concerns about this, please reach out to us.
-
Python 2.7: Pants v2.23.x is the last Pants release series which will be regularly tested with Python 2.7. Python 2.7 is no longer supported by its maintainers as of 1 January 2020. While Pants may continue to work with Python 2.7 in the near term, as of Pants v2.24.x, Pants will no longer officially support use of Python 2.7, and, consequently, will no longer be proactively tested with Python 2.7 in CI. Contributions to fix issues with Python 2.7 support will continue to be accepted, but will depend on any community contributions and will not consitute continued official support for Python 2.7.
-
The deprecations for the
--changed-dependeesoption and thedependeesgoal have expired. Use the equivalent--changed-dependentsoption ordependentsgoal instead.
New advanced options --file-downloads-retry-delay and --file-downloads-max-attempts allow configuration of the retry behavior when retryable errors occur while Pants is downloading files, for example, while downloading a http_source source.
The "Provided by" information in the documentation now correctly reflects the proper backend to enable to activate a certain feature.
This release introduces Target.origin_sources_blocks field that allows any
plugin to define dependencies on individual blocks of code rather that the
whole file. The --changed-since logic was updated to calculate fine grained
diff based on line numbers and compare the changed lines to
origin_sources_blocks to figure out which targets changed.
This feature is not used by any real plugin yet, but you can look at the test
plugin
for inspiration. To opt into the feature set the flag
--enable-target-origin-sources-blocks.
Pants has a new mechanism for @rule invocation in backends. In this release the following backends were migrated to use this new mechanism. There should not be any user-visible effects, but please be on the lookout for any unusual bugs or error messages.
cccuedebianjava.lintkotlin.lintmakeselfscala.lintsemgrepsqlswifttrufflehogyamllint
Support for parametrizing grouped parametrizations. (e.g. **parametrize(resolve=parametrize("a", "b"), ...)). This works for ___defaults__ as well, as long as it is specified per target type rather than using all.
The deprecation for the [GLOBAL].remote_auth_bearer_token_path option has expired. Use the [GLOBAL].remote_auth_bearer_token = "@/path/to/file" option instead.
The output_path field present on targets which can be packaged by pants package (for instance pex_binary(output_path=...)) is now based on a template so that you can use parts of output_path's default behavior when overriding it on a target. For example, you can use the template replacement ${{spec_path_normalized}} to obtain the default output directory for the target (i.e., the directory in which the target lives with slashes replaced by dots).
A new option --experimental-report-test-result-info is added to the [test] config section. Enabling this option will
produce a file on disk with information that would tell you more about the test results. For now, it reports only
the source of the results. The tests might have been executed locally or remotely, but they might have been retrieved
from the local or remote cache, or be memoized.
Knowing where the test results come from may be useful when evaluating the efficiency of the caching strategy and the nature of the changes in the source code that may lead to frequent cache invalidations.
buildifier was added to the list of supported formatters that can be used to format the BUILD files.
It may be helpful if your organization is migrating from Bazel and wants to keep the style of the BUILD files
consistent or if for any other reason you may want to adopt the formatting style that is enforced by buildifier.
The buildifier can be used on its own, but it can also be used in pair with a Python formatter, such as black
or ruff. For instance, you could first run buildifier to sort the target fields alphabetically,
and then run black to keep the style consistent with the rest of the Python code.
A new experimental pants.backend.experimental.nfpm backend was added to support building system packages with nFPM. nFPM describes itself as:
nFPM is Not FPM - a zero dependencies, simple
deb,rpm,apk,ipk, and arch linux packager written in Go.
This backend adds experimental support for building these package types: deb, rpm, apk, and archlinux. This plugin does not (yet) support building ipk packages (a recent addition to nFPM), though it support should be fairly straight forward to add if someone wants to work on it.
To use the nFPM backend, enable pants.backend.experimental.nfpm in your pants.toml, and create an nfpm_*_package target that depends on nfpm_content_* targets. This backend constructs the nfpm.yaml file that nFPM relies on to build packages. All nfpm.yaml fields (that make sense within pants) can be configured via the nfpm_*_package and nfpm_content_* targets.
This backend has extensive help documentation. Please use pants help to learn about the fields on these targets, or view the online documentation (for instance, npm_apk_package).
Learn general info about nFPM and available targets:
$ pants help backends | grep -A6 pants.backend.experimental.nfpm
$ pants help nfpm
$ pants help tools | grep -A3 nfpm
$ pants help targets | grep -A1 nfpm_
Learn about the nFPM package targets and their fields:
$ pants help nfpm_apk_package
$ pants help nfpm_archlinux_package
$ pants help nfpm_deb_package
$ pants help nfpm_rpm_package
Learn about the nFPM package content targets and their fields:
$ pants help nfpm_content_files
$ pants help nfpm_content_file
$ pants help nfpm_content_dirs
$ pants help nfpm_content_dir
$ pants help nfpm_content_symlinks
$ pants help nfpm_content_symlink
A new experimental pants.backend.experimental.tools.trufflehog backend was added to support
trufflehog secret scanning. The backend supports ignoring certain paths by adding, for example:
[trufflehog]
exclude = ["**/tests/*"]
The backend linter will also load a Trufflehog configuration file (passed via trufflehog -c trufflehog-config.yaml), as long as the configuration file is placed in the root of your codebase with filename: trufflehog-config.yaml
The tailor goal now has independent options for tailoring shell_sources and shunit2_tests targets. The option was split from tailor into tailor_sources and tailor_shunit2_tests.
The shell_command and adhoc_tool target types now check whether or not the values in output_files and output_directories fields were actually used to capture outputs from the invoked process. The new outputs_match_mode field on both target types configures how the checks are performed (including whether an error or just warning is produced).
Fixed a bug in how the PATH environment variable is modified to account for binary shims and dependencies of adhoc_tool and shell_command targets. The bug was that such paths overwrote any existing PATH variable provided by the user instead of augmenting the PATH value.
Changed some potentially confusing behavior in how outputs from adhoc_tool and shell_command running in an experimental_workspace_environment are found. Previously, for most invoked processes, Pants interpreted output_files and output_directories as relative paths relative to the configured working directory from the workdir field. In-workspace executions will now capture from the root of the temporary sandbox directory used during execution and will not prepend the working directory (which still applies to the invoked process). The output_files and output_directories fields continue to be interpreted relative to the working directory for executions in all other environments (e.g., local, remote, and Docker).
Added workspace_invalidation_sources field to adhoc_tool and shell_command target types. This new field allows declaring that these targets depend on files without bringing those files into the execution sandbox, but that the target should still be re-executed if those files change. This is intended to work with the workspace_environment support where processes are executed in the workspace and not in a separate sandbox.
Docker inference is improved. Pants can now make inferences by target address for targets supporting pants package, and file targets can be included by filename. See the documentation on Docker dependency inference for details
Experimental support for a Rust-based Dockerfile parser can be enabled via [dockerfile-parser].use_rust_parser option.
Fixed a bug where the internal Docker BuildKit parser would return <unknown> image_id if the BuildKit output used step durations.
Added new --docker-optional-tools option to allow the inclusion of tools in Docker backend execution sandboxes without failing the build if the tools are not present (unlike --docker-tools). The intent of this new option is to support inclusion of tools which are not available in all environments.
Support for including additional binaries in the Pants sandbox through the --golang-extra-tools option. The go tools may require other binaries in certain cases. E.g. When using go modules from a private git repository, go mod download will invoke git. See the documentation on Go Private Modules for details
Fix a bug where Pants raised an internal exception which occurred when compiling a Go package with coverage support when the package also had an external test which imported the base package.
Add support for the all: prefix to patterns used with the go:embed directive. The all: prefix includes files which start with _ or . which are ordinarilly excluded.
Fixed pulling helm_artifacts from OCI repositories.
Improve warning on dependent images not being found. Pants can now validate that values passed into Helm charts that will be used for container images are valid docker_image targets or known 3rd-party images. See the documentation in the helm-infer subsystem.
Added option [helm-infer].deployment_dependencies to disable costly parsing of k8s manifests.
Pants now ships with experimental JSX support, including Prettier formatting and JS testing as part of the
pants.backend.experimental.javascript backend.
The default versions of some tools have been upgraded, particularly Node.js being upgraded by 3 major versions:
| tool | previous version | new version |
|---|---|---|
| Node.js | 16.x | 22.6.0 |
| npm | 8.5.5 | 10.8.2 |
| pnpm | - | 9.5.0 |
| yarn | - | 1.22.22 |
Nodejs processes configured with extra_env_vars, e.g.
javascript_test,
now supports extending the PATH variable of such processes. Passing extra_env_vars=["PATH=/usr/bin"] was previously
silently ignored.
Two issues with pants corepack integration has been resolved:
- The
"packageManager"package.json field is now respected for other package.json than the one at the build root. Previously, if for example a nodejs tool was configured with a resolve based off of such a package.json, the bug caused pants to invokecorepacks default versions of the package managers instead. - The pants.toml option
[nodejs].package_managercan now be assigned any of the supported package managers (npm, pnpm, yarn) without providing a corresponding[nodejs].package_managersversion setting. The version is then entirely handled bycorepack. Previously this mode caused pants to fail.
The internal installation mechanism for node_modules has changed. Previously, Pants installed each package separately in sandboxes and merged the results, creating a node_modules for all dependent packages in the workspace. Now, this is delegated to the package managers, using each package manager's support for workspaces.
This fixes an issue with integrity file collisions when newer versions of package managers (e.g. the hidden lockfiles introduced in npm v7).
pants export --resolve=<js-resolve> now has basic support for exporting the package manager installation artifacts
including node_modules. This can be used to inspect the installation, or to enable IDE:s to discover the packages.
Pants will output a more helpful error message if there is no name field defined in the package.json file, or if the name field is empty.
Pants now applies dependency inference according to the most permissive "bundler" setting according to jsconfig.json, when a jsconfig.json is part of your javascript workspace.
Experimental TSX support has also been included as part of the pants.backend.experimental.typescript backend.
Dependency inference has been extended to support file-based imports.
These imports
// in src/ts/index.ts
import { x } from "./localModuleA";
import { y } from "./localModuleB";would be discovered as these modules provided they exist on disk:
$ pants dependencies src/ts/index.ts
src/ts/localModuleA.ts
src/ts/localModuleB.ts
When the jvm.reproducible_jars flag is set resources jars are now also made reproducible, previously it was assumed resources jars are reproducible without additional action.
Lockfiles are now deterministic as the dependency coordinates to be resolved are sorted before being passed to couriser.
All JVM tools have been refactored to use a different configuration mechanism. This includes the internal dependency parsers for Java, Kotlin, and Scala; internal JarTool, StripJarTool, and JarJar; and the OpenAPI code generator. This new mechanism should have parity.
Source files no longer produce a dependency on Scala plugins. If you are using a Scala plugin that is also required by the source code (such as acyclic), please add an explicit dependency or set the packages field on the artifact.
The deprecation for crossversion="partial" on scala_artifact has expired. Use crossversion="binary" instead.
The Scala dependency inference now understand usages of the _root_ package name as a marker for disambiguating between colliding dependencies and will try to resolve those symbols as absolute. For instance, import _root_.io.circe.syntax will now be understood as an import of io.circie.syntax.
Scala inference can also now identify dependencies between files when types are being used applied to other terms (i.e. nested function calls).
The BSP (Build Server Protocol) support has been moved out of the Pants core into several new backends to faciliate disabling this support if it is not needed. The new backends are:
pants.backend.experimental.bsp(core)pants.backend.experimental.java.bsp(Java support)pants.backend.experimental.scala.bsp(Scala support)
Enable the core pants.backend.experimental.bsp backend and one or more of the language-specific backends to enable BSP support.
Scala dependency inference now also understands types refered to only by pattern matching cases such as case MyType() =>. These used to require manually adding a dependency if the type was defined in a separate file even if it was in the same package. This is now inferred.
The function-as-a-service targets like python_google_cloud_function, python_aws_lambda_function, and python_aws_lambda_layer have had many changes to how they handle platforms:
- Deprecated: implicit platform inference for FaaS targets. Previously, Pants would infer a
--platformargument to PEX for targets withoutcomplete_platformsand with a runtime that doesn't have a built-in default complete platforms files. The--platformargument is a coarse summary of the target platform that regularly results in choosing incorrect native dependencies. In these cases, Pants now prompts the user to provide a value for thecomplete_platformsfield manually or infer the correct value where possible (see below). - To make this easier, the
python_google_cloud_functiontarget will now automatically select acomplete_platformsbased on the value of theruntimefield, similar to the AWS targets. - The
complete_platformsfield may now be specified as either afiletarget or aresourcetarget. - The
python_aws_lambda_functionandpython_aws_lambda_layertargets now allow specifying the machine architecture to use for the Lambda function via the newarchitecturefield. Additionally, both targets now support automatically selecting thecomplete_platformsused for building PEX files based on the values of thearchitectureandruntimefields together.
Deprecate the --export-py-hermetic-scripts option in favor of the new --export-py-non-hermetic-scripts-in-resolve option which allows configuring the hermetic scripts logic on a per-resolve basis.
A new entry_point_dependencies field is now available for python_tests and python_test targets. This allows tests
to depend on a subset (or all) of the entry_points defined on python_distribution targets. A dependency defined in
entry_point_dependencies emulates an editable install of those python_distribution targets. Instead of including
all of the python_distribution's sources, only the specified entry points are made available. The entry_points metadata
is also installed in the pytest sandbox so that tests (or the code under test) can load that metadata via pkg_resources.
To use this, enable the pants.backend.experimental.python backend.
Several fixes to Python-providing backends like the built-in pants.backend.python.providers.experimental.pyenv backend where Pants will install a Python interpreter rather than rely on one installed on the system:
- Exported virtualenvs can use those Pants-provided Pythons. Before Pants 2.23, virtualenv exports could only use pre-installed Python binaries.
- The pyenv provider now respects the patch version of the interpeter constraints.
- Lockfile generation now respects hermetic Python selection.
A new uv_requirements macro has been added to allow importing development dependencies specified in pyproject.toml files under the [tool.uv] section.
The default versions of some tools have been upgraded:
| tool | previous version | new version |
|---|---|---|
| pex | 2.3.1 | 2.16.2 |
| pyenv | 2.3.13 | 2.4.7 |
| pyright | 1.1.316 | 1.1.365 |
| ruff | 0.4.4 | 0.4.9 |
A new option [pex-cli].global_args has been
added to be able to pass arbitrary arguments to the pex tool as part of any Pants goal invocation.
This should make it a lot easier to modify behavior of pex tool without needing to make changes in the Pants codebase.
Fix running Python source files that have dashes in them (bug introduced in 2.20). For example: pants run path/to/some-executable.py
The docs for the check goal have been updated to state that third-party type stubs must be installed in the same resolve as the code.
The deprecation for the pants.backend.experimental.python.lint.ruff backend path has expired. Use pants.backend.experimental.python.lint.ruff.check instead.
Semgrep now allows configuring config file discovery via the new config_name option. In addition, it will now recursively discover all rules within a config directory, not just the immediate children.
Terraform supports caching providers.
The default version of Terraform has been updated from 1.7.1 to 1.9.0.
The tfsec linter now works on all supported platforms without extra config.
tfsec versions are now provided in semver format, without "v" prefixes.
tfsec now allows capturing reports generated using the report_name config.
Sandboxes for the experimental-deploy deployment (the execution of terraform apply) can now be preserved with --keep-sandboxes.
The terraform-hcl2-parser subsystem downgrades python-hcl2 version back to 4.3.0 by default to avoid parsing issues introduced afterwards.
Terraform Lockfiles now participate in the dependency graph. --changed-since will now include targets affected by the changed lockfile.
The Terraform backend supports creating lockfiles which support multiple platforms. See the platforms option documentation and the documentation on lockfiles for examples.
The pants.backend.experimental.tools.workunit_logger backend will now create directory specified by the logdir option if it doesn't already exist.
Fixed bug with workspace environment support where Pants used a workspace environment when it was searching for a local environment.
Support documenting macro constants using MY_CONSTANT: Annotated[some_type, Doc("my help text ...")] = some_value.
Fixed bug where files larger than 512KB were being materialized to a process's sandbox without write permissions if the file was only globbed by output_directories=(".",).
Fixed bug where using RuleRunner in plugin tests caused ValueError that complains about not finding build root sentinel files. Note that you may have to adjust your tests to account for the new BUILDROOT file that RuleRunner now injects in the sandbox it creates for each test. For example, a test that uses a ** glob might have to add !BUILDROOT to exclude the BUILDROOT file, or otherwise account for its presence when inspecting a sandbox or its digest.
Plugins may now provide "auxiliary" goals by implememting the auxiliary_goals function in their plugin registration module and returning one or more subclasses of pants.goal.auxiliary_goal.AuxiliaryGoal. An auxiliary goal is a special kind of goal which is invoked outside of the engine. The BSP (Build Server Protocol) support now uses this mechanism to move the experimental-bsp goal out of the Pants core rules. (The BSP rules used this support since running the BSP server cannot be done from within execution of the rules engine.)
Added support for plugins that implement provide PytestPluginSetup to inject additional sys.path entries. Simply pass a tuple of paths in PytestPluginSetup(extra_sys_path=(...)). This gets to pytest via PEX_EXTRA_SYS_PATH, similar to how scripts might modify PYTHONPATH when running pytest outside of pants.
Several intrinsics have been renamed more succinctly, to make them more readable and developer-friendly when called by name.
An execute_process_or_raise() alias has been added for the fallible_to_exec_result_or_raise rule, so that code that calls it by name on an implicitly executed process will be more readable.
Metadata for paths in the repository can now be requested via the PathMetadataRequest and PathMetadataResult types. This API is intended for rules which need access to the "full" metadata for a path.
For the full changelog, see the individual GitHub Releases for this series: https://github.com/pantsbuild/pants/releases