Configuration reference

For a first configuration, follow Getting started. This page is for looking up individual settings.

File location

Use native-packages.yaml or native-packages.yml in your working directory. To choose another file:

native-packages --config packaging/native-packages.yaml build --version 1.2.3

Configuration paths and hooks resolve from that file’s directory. Keep only one of the auto-discovered filenames, or use --config to select one. The configuration is YAML data; it does not evaluate Ruby or general template expressions. Use the replacement values listed below.

Top-level fields

Quote tool versions so they remain strings. A version mismatch reports the command needed to install and select the configured gem.

Package metadata

nfpm is named after the helper that writes Linux packages and MSIX files. It holds the package’s metadata, files, dependencies, and package-manager settings. Native DMG and Inno targets also read the shared metadata.

Every target needs nonempty maintainer, description, and license values. Non-native targets need a contents list. The shared package name may contain letters, digits, dots, underscores, and hyphens, starting with a letter or digit.

nfpm:
  name: hello
  description: A small greeting application
  maintainer: Your Name <you@example.com>
  license: MIT
  contents:
    - src: '@PAYLOAD@/hello'
      dst: /usr/bin/hello
      file_info:
        mode: 0755

You can move that mapping to a file and use nfpm: packaging/package.yml. A target can supply an nfpm mapping or filename to override shared values. Maps merge recursively; lists replace in full.

The package name, version, platform, and architecture come from the shared name, build version, and target. Avoid conflicting declarations under nfpm. Format-specific architecture names belong under sections such as deb.arch. For additional metadata, scripts, and format overrides, see the nFPM configuration reference.

Targets

Each key under targets is an ID such as linux-amd64. IDs use lowercase letters, digits, and hyphens, starting with a letter or digit.

Formats are deb, rpm, archlinux, apk, ipk, srpm, msix, dmg, and inno. See Supported platforms for their requirements.

Windows targets select only [msix] or [inno]; macOS targets select [dmg]. DMG and Inno each require a separate binary target. SRPM requires a separate kind: source target with only [srpm].

Inputs

Declare at least local or release_asset, and supply the field needed for your chosen build mode. Native targets require kind: directory and local. Binary release inputs always need a matching published checksum.

Regular package inputs reject symbolic links. Use explicit installed symlink entries in contents. Native inputs preserve safe internal relative links.

Native commands

native:
  command: [ruby, packaging/dmg.rb, '@PAYLOAD@', '@PACKAGE@', '@VERSION@']
  output: 'hello-@TAG@-macos-arm64.dmg'

The command must be a nonempty argument list containing @PACKAGE@, and must create only that output file. output is a filename ending in .dmg or .exe. See macOS and Windows installers for the script contract and a complete DMG example.

Hooks

before_build runs once per selected target before copying local input. It is skipped in release mode. after_package runs once per generated package in either mode, before checksums are recorded.

before_build: [./scripts/build-linux.sh, '@ARCH@']
after_package: [pwsh, -File, packaging/sign.ps1, '@PACKAGE@']

Hooks run in the configuration directory with NATIVE_PACKAGES_TARGET and NATIVE_PACKAGES_VERSION. They are argument lists, so use a script for shell pipelines. validate, doctor, and dry runs never execute build hooks. The output hook must preserve the package’s filename and file set.

For DMGs, automatic Apple input signing finishes before the native command. DMG signing and notarization run after after_package, before the final hash. See Apple signing and notarization.

Replacement values

Strings can contain @KEY@ values. Unknown or unavailable values cause an error.

Target values are available within target definitions and package metadata, not global recipe templates. before_build runs before the payload exists; use it to produce input.local.

Release

release:
  repository: your-name/hello
  checksums: checksums.txt
  prereleases: false

repository is the GitHub owner/repository for downloads and package uploads. checksums is a filename, defaulting to checksums.txt. prereleases: true opts into the formats and version rules described in Prereleases.

Version and timestamp

build --version 1.2.3 uses local inputs. build --release v1.2.3 supplies the version and uses release inputs. If both options are given, their versions must agree. Omitting both requires an exact supported release tag at HEAD.

Versions are stable MAJOR.MINOR.PATCH unless prereleases are enabled. A leading v is accepted. Build timestamps use SOURCE_DATE_EPOCH, then the relevant Git commit’s timestamp, then the current time if Git metadata is unavailable. Set an explicit epoch for repeatable builds outside Git and for builds split across hosts.

Assets and templates

assets:
  AMD64:
    file: hello_@VERSION@_linux_amd64.tar.gz
    local: dist/hello_@VERSION@_linux_amd64.tar.gz
templates:
  arch/hello-bin/PKGBUILD: packaging/arch/hello-bin/PKGBUILD.in

Asset keys use uppercase letters, digits, and underscores, starting with a letter. Each asset needs file; local builds also need local. An optional url overrides its release download location. Downloads are checked against release checksums by default. For a source archive omitted from the published checksum list, explicitly set checksummed: false; its computed SHA-256 still appears in the rendered recipe.

templates maps output paths under recipes/ to source paths relative to the configuration. See Distribution recipes for a complete example.

Deferred recipe generation

build --defer-recipes skips global assets and templates. Use aggregate --finalize-recipes once all package builds and remaining local assets are available. No additional configuration fields are needed. See Building across platforms for prerequisites, asset matching, and publication rules.

Repositories

Each entry under repositories names a destination. These settings apply to stage, diff, publish, and status:

GitHub PR entries also need repository (upstream owner/repo) and fork_owner. GitLab MR entries need repository, fork_repository, host, and token_env (the environment variable holding the GitLab token). Submission destinations need a fork, a proposal_branch, and a reviewed --body-file when publishing. GitHub requests use authenticated gh; direct Git pushes use your configured Git credentials.

Libraries

Add a mapping from a shared library’s filename to its distribution package:

libraries:
  libexample.so.1:
    deb: libexample1
    rpm: libexample

Mappings extend the built-in DEB/RPM table. A mapping for an existing library replaces that library’s mapping, so include both formats if needed. Verify package names against your supported distribution versions.

Revisions and version checks

To regenerate a recipe with a new package revision for the same app version:

revisions:
  '1.2.3':
    arch/hello-bin/PKGBUILD: 2

That template receives @PKGREL@ as 2; other versions and templates default to 1. This setting controls recipe revisions, not the nfpm.release field.

For Cargo version checks:

version_file: Cargo.toml
version_section: package

Run native-packages check-version v1.2.3 to compare the manifest version with the tag. Use version_section: workspace.package for a workspace version.

Output and publication

A build writes to a fresh dist/packages/<version>/ by default. Packages live under packages/<target>/<format>/. build.json records configuration identity, targets, input/output hashes, and validation results.

Publication verifies the files against the manifest. It requires every format for all configured targets unless exact complete targets are selected with publish --target. See Publishing a release.

One configuration across native hosts

Build each native target on its host, then combine results with aggregate. Use the same configuration, version, and timestamp. The Linux reusable workflow can select Linux targets through its targets input. See Building across platforms.