Skip to main content
Version: 2.23 (prerelease)

nfpm_rpm_package

An RPM system package built by nFPM.

This will not install the package, only create an .rpm file that you can then distribute and install, e.g. via pkg.

See https://www.pantsbuild.org/nfpm-rpm-package.

Backend: pants.backend.experimental.nfpm

package_name​

str
required

The package name.

version​

str
required

The 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
default: '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'

compression​

'gzip' | 'lzma' | 'xz' | 'zstd' | None
default: 'gzip:-1'

The compression algorithm to use on the rpm package.

This takes a compression algorithm and optionally a compression level. To specify a level, use 'algorithm:level'. Specifying a compression level is only valid for 'gzip' or 'zstd'.

Here are several gzip examples with and without the optional compression level (-1 means use the default level which is 5; 9 is the max).

'gzip:9' 'gzip:0' 'gzip:-1' 'gzip:5' 'gzip'

Here are several zstd examples. Note that nFPM uses a library that only defines four named compression levels, and then maps the zstd integer levels to those. You may specify the zstd level as an integer, or using these names: https://github.com/klauspost/compress/tree/master/zstd#status

'zstd:fastest' 'zstd:default' 'zstd:better' 'zstd:best' 'zstd:3' 'zstd:9' 'zstd'

conflicts​

Iterable[str] | None

dependencies​

Iterable[str] | None
default: None

Addresses 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] | None
default: None

List of package requirements (for package installers).

The 'depends' field has install-time requirements that can use version selectors (with one of <, <=, =, >=, > surrounded by spaces), where the version is formatted: [epoch:]version[-release]

  • "git" - "bash < 5" - "perl >= 9:5.00502-3"

The rpm file header uses the term "requires" for this. This field is named "depends" because that is the term used by nFPM.

WARNING: This is NOT the same as the 'dependencies' field! It does not accept pants-style dependencies like target addresses.

See: https://rpm-software-management.github.io/rpm/manual/dependencies.html#requires https://rpm-software-management.github.io/rpm/manual/dependencies.html#versioning https://ftp.osuosl.org/pub/rpm/max-rpm/s1-rpm-inside-tags.html#S3-RPM-INSIDE-REQUIRES-TAG https://ftp.osuosl.org/pub/rpm/max-rpm/s1-rpm-depend-manual-dependencies.html#S2-RPM-DEPEND-REQUIRES-TAG

description​

str | None
default: None

A human-readable description of the target.

Use pants list --documented :: to see all targets with descriptions.

ghost_contents​

Iterable[str] | None
default: None

A list of files that this package owns, but that this package does not include.

Examples of ghosted files include: - A log file or a state file that does not exist until runtime. - A binary that is managed by 'alternatives'.

RPM specs use the %ghost directive to list these ghosted files.

Each file in this list gets passed to nFPM via the 'contents' field with 'type=ghost'. Then nFPM translates that into the appropriate RPM header. The file does not need to exist in your pants workspace as nFPM directly adds it to the RPM header.

See: https://ftp.osuosl.org/pub/rpm/max-rpm/s1-rpm-inside-files-list-directives.html#S3-RPM-INSIDE-FLIST-GHOST-DIRECTIVE

N.B.: Packages distributed by Fedora must use this if they provide 'alternatives'. https://docs.fedoraproject.org/en-US/packaging-guidelines/Alternatives/#_how_to_use_alternatives

group​

str | None
default: None

For older rpm-based distros, this groups packages by their functionality.

'group' is a path-like string to allow for hierarchical grouping of applications like "Applications/Editors".

See: https://ftp.osuosl.org/pub/rpm/max-rpm/s1-rpm-inside-tags.html#S3-RPM-INSIDE-GROUP-TAG

N.B.: This field is only useful when packaging for old distros (EL 5 or earlier). All newer rpm-based distros have deprecated--and do not use--this field. https://docs.fedoraproject.org/en-US/packaging-guidelines/#_tags_and_sections

homepage​

str | None
default: None

The URL of this package's homepage like "https://example.com&#x22;.

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 | None
default: None

The 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
default: '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.

See also: https://reproducible-builds.org/docs/timestamps/

output_path​

str | None
default: '${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.

packager​

str | None
default: None

The name and email address of the packager or packager organization.

The 'packager' 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]>" This format is the conventional format; it not a hard requirement.

See: https://ftp.osuosl.org/pub/rpm/max-rpm/s1-rpm-inside-tags.html#S3-RPM-INSIDE-PACKAGER-TAG

N.B.: Packages distributed by Fedora do not use this field. https://docs.fedoraproject.org/en-US/packaging-guidelines/#_tags_and_sections

platform​

str | None
default: '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.

prefixes​

Iterable[str] | None
default: None

A list of relocatable prefixes (to support relocatable rpms).

Defining 'prefixes' allows rpm to install your package at an alternative prefix if the user requests that using the --prefix flag. This list is the default list of prefixes used by this package. If rpm relocates an installation of this package, it will strip off each of these prefixes, replacing them with the --prefix requested by the user.

Before using this, ensure that any packaged software can actually run from alternate prefixes, and watch out for any absolute symlinks targets which might not be relocated correctly.

RPM specs use the Prefix: tag to list each prefix in this list.

See: https://rpm-software-management.github.io/rpm/manual/tags.html#packages-with-files https://ftp.osuosl.org/pub/rpm/max-rpm/ch-rpm-reloc.html https://ftp.osuosl.org/pub/rpm/max-rpm/s1-rpm-inside-tags.html#S3-RPM-INSIDE-PREFIX-TAG

provides​

Iterable[str] | None
default: None

A list of virtual packages or file paths that this package provides.

This is used so that multiple packages can be be alternatives for each other. The list can include virtual package names and/or file paths. For example the bash package includes these in 'provides':

  • "bash" - "/bin/sh" - "/bin/bash"

This means another package could also provide alternative implementations for the "bash" package name and could provide "/bin/sh" and/or "/bin/bash".

N.B.: Virtual package names must not include any version numbers.

See: https://rpm-software-management.github.io/rpm/manual/dependencies.html#provides https://ftp.osuosl.org/pub/rpm/max-rpm/s1-rpm-depend-manual-dependencies.html#S2-RPM-DEPEND-PROVIDES-TAG

recommends​

Iterable[str] | None
default: None

List of weak package requirements (for package installers).

This is like the 'depends' field, but the package resolver can ignore the requirement if it cannot resolve the packages with it included. If an entry in 'recommends' is ignored, no error or warning gets reported.

The 'recommends' field has the same syntax as the 'depends' field.

See: https://rpm-software-management.github.io/rpm/manual/dependencies.html#weak-dependencies

replaces​

Iterable[str] | None
default: None

A list of packages that this package obsoletes (replaces).

When a pacakge name changes or splits, rpm uses "obsoletes" (ie the 'replaces' field) on the new package to list the old package name(s) that can be upgraded to this package.

The rpm file header uses the term "obsoletes" for this. This field is named "replaces" because that is the term used by nFPM.

See: https://rpm-software-management.github.io/rpm/manual/dependencies.html#obsoletes

scripts​

dict | None
default: None

Map of install scriptlet 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, RPM uses the following scriptlet tag names instead and runs them before/after the indicated phase:

| nFPM term | RPM scriptlet | RPM phase |
+-------------+---------------+-------------+
| preinstall | %pre | install |
| postinstall | %post | install |
| preremove | %preun | uninstall |
| postremove | %postun | uninstall |
| pretrans | %pretrans | transaction |
| posttrans | %posttrans | transaction |
| verify | %verifyscript | verify |

Please consult the RPM docs to understand what is required of these scripts.

See: https://docs.fedoraproject.org/en-US/packaging-guidelines/Scriptlets/ https://rpm-software-management.github.io/rpm/manual/tags.html#scriptlets https://ftp.osuosl.org/pub/rpm/max-rpm/s1-rpm-inside-scripts.html#S2-RPM-INSIDE-ERASE-TIME-SCRIPTS

suggests​

Iterable[str] | None
default: None

List of very weak package requirements (for package installers).

These suggestions are ignored by the package resolver. They are merely shown to the user as optional packages that the user might want to also install.

The 'suggests' field has the same syntax as the 'depends' field.

See: https://rpm-software-management.github.io/rpm/manual/dependencies.html#weak-dependencies

summary​

str | None
default: None

A one-line description of the packaged software.

If unset, nFPM will use the first line of 'description' for the 'summary'.

See: https://ftp.osuosl.org/pub/rpm/max-rpm/s1-rpm-inside-tags.html#S3-RPM-INSIDE-SUMMARY-TAG

tags​

Iterable[str] | None
default: None

Arbitrary 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.

vendor​

str | None
default: None

The entity responsible for packaging (typically an organization).

See: https://ftp.osuosl.org/pub/rpm/max-rpm/s1-rpm-inside-tags.html#S3-RPM-INSIDE-VENDOR-TAG

N.B.: Packages distributed by Fedora do not use this field. https://docs.fedoraproject.org/en-US/packaging-guidelines/#_tags_and_sections

version_epoch​

int | None
default: None

A 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 | None
default: None

This 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 | None
default: None

This 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 | None
default: 1

The 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
default: '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.