nfpm_deb_package
A Debian system package built by nFPM.
This will not install the package, only create a .deb file that you can then distribute and install, e.g. via pkg.
See https://www.pantsbuild.org/nfpm-deb-package.
Backend: pants.backend.experimental.nfpm
maintainer
strThe name and email address of the package maintainer.
The 'maintainer' is used to identify who actually packaged the software, as opposed to the author of the software.
The name is first, then the email address inside angle brackets <> (in RFC5322 format). For example: "Foo Bar <[email protected]>"
See: https://www.debian.org/doc/debian-policy/ch-controlfields.html#maintainer
package_name
strThe package name.
version
strThe package version (preferably following semver).
If 'version_schema' is not 'semver', then this should not be prefixed with a 'v' because some package managers, like deb, require the version start with a digit.
See the 'version_schema' field's help for more details about how this field gets parsed by nFPM when it is 'semver'.
arch
str | None'amd64'The package architecture.
This should be a valid GOARCH value (or GOARCH+GOARM) that nFPM can convert into the package-specific equivalent. Otherwise, pants tells nFPM to use this value as-is.
nFPM conversion from GOARCH to package-specific value is documented here: https://nfpm.goreleaser.com/goarch-to-pkg/
Use one of these values unless you need nFPM to use your value as-is: '386', 'all', 'amd64', 'arm5', 'arm6', 'arm7', 'arm64', 'loong64', 'mips', 'mipsle', 'mips64', 'mips64le', 'ppc64', 'ppc64le', 'riscv64', 's390', 's390x', 'sparc64', 'wasm'
breaks
Iterable[str] | NoneNoneA list of packages which would break if this package would be installed.
The installation of this package is blocked (by package installers) if any packages in this list are already installed. This is a looser package relationship than the 'conflicts' field, because it allows the package installer more flexibility on ordering package installs and removals (For example, if this package breaks "bar", then "bar" can be removed after this package when it gets removed in the same package install transaction).
For example, this is how to declare that this breaks package foo, but only if foo version 2.5 or less is installed and it breaks package bar no matter what version is installed.
- "foo (<2.6)" - "bar"
compression
'gzip' | 'none' | 'xz' | 'zstd' | None'gzip'The compression algorithm to use on the deb package.
conflicts
Iterable[str] | NoneNoneA list of packages that this package conflicts with.
Generally, you should use 'breaks' instead of 'conflicts', because 'conflicts' imposes much more strict requirements on the order of package installs and removals. Use this if the conflicting packages must be completely uninstalled before this package can be installed.
For example, this is how to declare that this package conflicts with the foo (version 2.5 or less) and bar packages, so they must be uninstalled before this package can be installed.
- "foo (<2.6)" - "bar"
See: https://www.debian.org/doc/debian-policy/ch-relationships.html#conflicting-binary-packages-conflicts
dependencies
Iterable[str] | NoneNoneAddresses to other targets that this target depends on, e.g. ['helloworld/subdir:lib', 'helloworld/main.py:lib', '3rdparty:reqs#django'].
This augments any dependencies inferred by Pants, such as by analyzing your imports. Use pants dependencies or pants peek on this target to get the final result.
See https://www.pantsbuild.org/2.23/docs/using-pants/key-concepts/targets-and-build-files for more about how addresses are formed, including for generated targets. You can also run pants list :: to find all addresses in your project, or pants list dir to find all addresses defined in that directory.
If the target is in the same BUILD file, you can leave off the BUILD file path, e.g. :tgt instead of helloworld/subdir:tgt. For generated first-party addresses, use ./ for the file path, e.g. ./main.py:tgt; for all other generated targets, use :tgt#generated_name.
You may exclude dependencies by prefixing with !, e.g. ['!helloworld/subdir:lib', '!./sibling.txt']. Ignores are intended for false positives with dependency inference; otherwise, simply leave off the dependency from the BUILD file.
depends
Iterable[str] | NoneNoneList of package dependencies (for package installers).
The 'depends' field has install-time dependencies that can use version selectors (with one of <<, <=, =, >=, >> in parentheses) or use | to specify package alternatives that equally satisfy a dependency.
- "git" - "libc6 (>= 2.2.1)" - "default-mta | mail-transport-agent"
Make sure to include package dependencies of this package as well as any packages required by the postinstall, postupgrade, or preremove scripts.
WARNING: This is NOT the same as the 'dependencies' field! It does not accept pants-style dependencies like target addresses.
See: https://www.debian.org/doc/debian-policy/ch-relationships.html
description
str | NoneNoneA human-readable description of the target.
Use pants list --documented :: to see all targets with descriptions.
fields
Dict[str, str] | NoneNoneAdditional fields for the control file. Empty fields are ignored.
Debian control files supports more fields than the options that are exposed by nFPM and the pants nfpm backend. Debian even allows for user-defined fields. So, this 'fields' field provides a way to add any additional fields to the debian control file.
See: https://www.debian.org/doc/debian-policy/ch-controlfields.html#user-defined-fields
homepage
str | NoneNoneThe URL of this package's homepage like "https://example.com".
This field is named "homepage" instead of "url" because that is the term used by nFPM, which adopted the term from deb packaging. The term "url" is used by apk, archlinux, and rpm packaging.
license
str | NoneNoneThe license of this package.
Where possible, please try to use the SPDX license identifiers (for example "Apache-2.0", "BSD-3-Clause", "GPL-3.0-or-later", or "MIT"): https://spdx.org/licenses/
For more complex cases, where the package includes software with multiple licenses, consider using an SPDX license expression: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/
See also these rpm-specific descriptions of how to set this field (this is helpful info even if you are not using rpm): https://docs.fedoraproject.org/en-US/legal/license-field/
nFPM does not yet generate the debian/copyright file, so this field is technically unused for now. Even for deb, we recommend using this field to document the software license for this package. See also these pages about specifying a license for deb packaging: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/#license-specification https://wiki.debian.org/Proposals/CopyrightFormat#Differences_between_DEP5_and_SPDX
mtime
str | None'1980-01-01T00:00:00Z'The file modification time as an RFC 3339 formatted string.
For example: 2008-01-02T15:04:05Z
The format is defined in RFC 3339: https://rfc-editor.org/rfc/rfc3339.html
NOTE: This field does NOT set the mtime for package contents. It sets the build time in package metadata (for package types that have that metadata), as well as the file modification time for files that nFPM generates in the package. To set the mtime for package contents, use the file_mtime field on the relevant nfpm_content_* targets.
The default value is '1980-01-01T00:00:00Z'. You may also override the default value by setting [nfpm].default_mtime in pants.toml, or by setting the SOURCE_DATE_EPOCH environment variable.
output_path
str | None'${spec_path_normalized}/${target_name_normalized}${file_suffix}'Where the built directory tree should be located.
If undefined, this will use the path to the BUILD file, followed by the target name. For example, src/project/packaging:rpm would be src.project.packaging/rpm/.
Regardless of whether you use the default or set this field, the package's file name will have the packaging system's conventional filename (as understood by nFPM). So, an rpm using the default for this field, the target src/project/packaging:rpm might have a final path like src.project.packaging/rpm/projectname-1.2.3-1.x86_64.rpm. Similarly, for deb, the target src/project/packaging:deb might have a final path like src.project.packaging/deb/projectname_1.2.3+git-1_x86_64.deb. The other packagers have their own formats as well.
When running pants package, this path will be prefixed by --distdir (e.g. dist/).
Warning: setting this value risks naming collisions with other package targets you may have.
platform
str | None'linux'The package platform or OS.
You probably do not need to change the package's OS. nFPM is designed with the assumption that this is a GOOS value (since nFPM is part of the "goreleaser" project). But, nFPM does not do much with it.
For archlinux and apk, the only valid value is 'linux'. For deb, this can be used as part of the 'Architecture' entry. For rpm, this populates the "OS" tag.
predepends
Iterable[str] | NoneNoneList of package unpack-time dependencies (for package installers).
In most cases, you should use the 'depends' field instead of this one to declare install-time package dependencies. The 'predepends' field has install-time dependencies that need to be available (including unpacking, pre-install, and post-install scripts) before unpacking or installing this package.
Make sure to include packages required by the preinst script.
WARNING: This is NOT the same as the 'dependencies' field! It does not accept pants-style dependencies like target addresses.
See: https://www.debian.org/doc/debian-policy/ch-relationships.html
priority
'extra' | 'important' | 'optional' | 'required' | 'standard' | None'optional'Indicates how important the package is for OS functions.
Most packages should just stick with the default priority: "optional".
See: https://www.debian.org/doc/debian-policy/ch-archive.html#s-f-priority
Valid priorities are listed here: https://www.debian.org/doc/debian-policy/ch-archive.html#priorities
provides
Iterable[str] | NoneNoneA list of virtual packages that this package provides.
Each entry can be either a package name, or a package name with a version. The version, however, must be declared with = (not <<, <=, etc)
For example, these declare virtual packages foo and bar.
- "foo" - "bar (=1.0.0)"
If several packages declare the same 'provides', then they might need to declare that they conflict with each other using 'conflicts' if, for example, they also install a binary with the same path.
See: https://www.debian.org/doc/debian-policy/ch-relationships.html#virtual-packages-provides
recommends
Iterable[str] | NoneNoneList of optional package dependencies (for package installers).
The 'recommends' field has packages that can be excluded in "unusual installations" but should generally be installed with this package.
WARNING: This is NOT the same as the 'dependencies' field! It does not accept pants-style dependencies like target addresses.
See: https://www.debian.org/doc/debian-policy/ch-relationships.html
replaces
Iterable[str] | NoneNoneA list of packages that this package replaces or partially replaces.
To declare that this package partially replaces another package, by taking ownership of files in that package, include that other package in both 'replaces' and 'breaks'.
If this package completely replaces the other package, you can force its removal by including the other package in both 'replaces' and 'conflicts' (and 'provides' if it is a virtual package).
scripts
dict | NoneNoneMap of maintainer script source files for the deb package.
This maps the script type (key) to the script source file (value). Each of the script source file(s) must be provided via 'dependencies'. The script types are the names used by nFPM. For reference, Debian uses the following file names instead:
| nFPM script | Debian file |
+-------------+-------------+
| preinstall | preinst |
| postinstall | postinst |
| preremove | prerm |
| postremove | postrm |
| config | config |
| templates | templates |
| rules | rules |
The pre* and post* scripts are used by dpkg at various stages of installing, upgrading, and removing the deb package.
The config script and templates file are part of the Debian Configuration Management Specification. config can run at any time, including before preinst to prompt the user for package configuration using debconf. templates is used by debconf to create those prompts.
The rules script is only needed for source packages. This script is an executable makefile that can build a binary from the packaged sources.
Please consult the Debian docs to understand when dpkg or debconf will run each of these scripts, what assumptions you can safely make when they run, and how dpkg handles a failure.
See: https://www.debian.org/doc/debian-policy/ch-binary.html#maintainer-scripts https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html https://www.debian.org/doc/debian-policy/ap-flowcharts.html http://www.fifi.org/doc/debconf-doc/tutorial.html https://www.debian.org/doc/debian-policy/ch-source.html#s-debianrules
section
str | NoneNoneWhich section, or application area, this package is part of.
For example, you could classify your application under the "education" section, or under a language section like "python", "rust", or "ruby".
See: https://www.debian.org/doc/debian-policy/ch-archive.html#sections
Valid sections are listed here: https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections
suggests
Iterable[str] | NoneNoneA list of package suggestions (for package installers).
These packages are completely optional, but could be useful for users of this package to install as well.
See: https://www.debian.org/doc/debian-policy/ch-relationships.html
tags
Iterable[str] | NoneNoneArbitrary strings to describe a target.
For example, you may tag some test targets with 'integration_test' so that you could run pants --tag='integration_test' test :: to only run on targets with that tag.
triggers
dict | NoneNoneCustom deb triggers.
nFPM uses this to create a deb triggers file, so that the package can declare its "interest" in named triggers or declare that the indicated triggers should "activate" when this package's state changes.
The Debian documentation describes the format for the triggers file. nFPM simplifies that by accepting a dictionary from trigger directives to lists of trigger names.
For example (note the underscore in "interest_noawait"):
triggers={"interest_noawait": ["some-trigger", "other-trigger"]}
Gets translated by nFPM into:
interest-noawait some-trigger interest-noawait other-trigger
See: https://wiki.debian.org/DpkgTriggers https://www.mankier.com/5/deb-triggers
version_epoch
int | NoneNoneA package with a higher version epoch will always be considered newer. This is primarily useful when the version numbering scheme has changed.
Debian and RPM documentation warn against using epoch in most cases: https://www.debian.org/doc/debian-policy/ch-controlfields.html#epochs-should-be-used-sparingly https://rpm-packaging-guide.github.io/#epoch
When this field is None (the default) nFPM will use "" for deb packages, and "0" for rpm packages.
N.B.: The nFPM documentation incorrectly notes that nFPM can parse this from the 'version' field; the nFPM code actually does not replace or update this.
version_metadata
str | NoneNoneThis is package-manager specific metadata for the version.
This is typically prefixed with a "+" in the version. If the version contains "+git", then the 'version_metadata' is "git". Debian has various conventions for this metadata, including things like "+b", "+nmu", "+really", and "+deb10u1". See: https://www.debian.org/doc/debian-policy/ch-controlfields.html#special-version-conventions
nFPM extracts the default for this from 'version' if it is semver compatible. If you set 'version_metadata', then any metadata component of 'version' gets discarded.
version_prerelease
str | NoneNoneThis is a pre-release indicator like "alpha" or "beta" and often includes a numeric component like "rc1" and "rc2".
For apk and archlinux, version and prerelease are merely concatenated. For deb and rpm, prerelease is typically prefixed with a "~" in the version.
nFPM extracts the default for this from 'version' if it is semver compatible. If you set 'version_prerelease', then any prerelease component of 'version' gets discarded.
version_release
int | None1The release or revision number for a given package version.
Increment the release each time you release the same version of the package. Often, these releases allow for correcting metadata about a package or to rebuild something that was broken in a previous release of that version.
Reset this to 1 whenever you bump the 'version' field.
N.B.: nFPM does NOT parse this from the 'version' field.
version_schema
'none' | 'semver' | None'semver'Which schema the 'version' field follows.
nFPM only supports two schemas for now: semver, none
If this is "none", then nFPM will use 'version' as-is.
If this is "semver", then nFPM will parse 'version' into its constituent parts using a lenient algorithm: It will strip a v prefix and will accept versions with fewer than 3 components, like v1.2. If parsing fails, then the version is used as-is. If parsing succeeds, nFPM replaces config options with the parsed components.
The 'version' field always gets replaced with a dotted 3 part version (Major.Minor.Patch).
The 'version_prerelease' field is only updated if not set. It gets the "dev", "alpha", "rc", or similar parsed prerelease indicator.
The 'version_metadata' field is only updated if not set. This will be set with "git" when the version contains "+git" and similar metadata tags.
The 'version_release' and 'version_epoch' fields are NOT replaced by components parsed from 'version'.
N.B.: Some of these fields are not available for all package types.
This field is named "version" because that is the term used by nFPM. Though deb and rpm packaging also use "version", this is known as "pkgver" in apk and archlinux packaging.