GitHub Releases

Prebuilt binaries for Linux and macOS (amd64 and arm64) are attached to every release.

pre-commit hook

repos:
  - repo: https://github.com/jmelahman/pkglint
    rev: 18319ffe6c6ea34d19fe0660ac2e99578cb883f0 # frozen: v1.7.0
    hooks:
      - id: pkglint

Pass flags with args:, e.g. args: [--ignore, PB105, --fail-on, critical].

yay hook (yay ≥ 13)

To lint every AUR package before yay builds it, add the snippet below to ~/.config/yay/init.lua. It runs after each PKGBUILD is downloaded, before the diff/edit menus or any build, and asks before continuing if pkglint finds anything.

-- pkglint: lint each AUR PKGBUILD before yay shows menus or builds anything.
-- PKGLINT_FAIL_ON overrides the threshold per run (info|warn|error|critical).
local function shquote(s) return "'" .. s:gsub("'", [['\'']]) .. "'" end

yay.create_autocmd("AURPreInstall", {
  desc = "pkglint: refuse packages with static findings at or above the threshold",
  callback = function(event)
    local fail_on = os.getenv("PKGLINT_FAIL_ON") or "error"
    -- --no-inline-ignores: the maintainer's "# pkglint: ignore=" doesn't get to
    -- hide findings from the person installing the package.
    local status = os.execute("pkglint --no-inline-ignores --fail-on "
      .. shquote(fail_on) .. " " .. shquote(event.data.dir))
    if status == 0 then return end
    io.write(event.match .. ": pkglint reported findings. Continue anyway? [Y/n] ")
    io.flush()
    -- Enter continues; "n" or no terminal to read from (EOF) refuses.
    local answer = io.read("*l")
    if answer == nil or answer:match("^%s*[nN]") then
      yay.abort("refused by pkglint")
    end
  end,
})

Usage

pkglint [flags] [path ...]     # package dirs, PKGBUILD files, or *.pkg.tar.* (default: .)

  --format text|json|sarif     # output format (sarif for code scanning)
  --fail-on SEVERITY           # exit 1 at or above: info, warn (default), error, critical, never
  --ignore PB105,PB206         # disable rules
  --select PB101,PB304         # check only these rules
  --fix                        # apply safe auto-fixes in place
  --unsafe-fix                 # also apply behavior-changing fixes
  --diff                       # with a fix flag: show changes instead of writing them
  --offline                    # with --fix: skip fixes that need the network
  --add-ignores                # suppress every current finding with an inline directive
  --no-inline-ignores          # disregard ignore directives (audit an untrusted package)
  --verbose                    # also list packages with no findings
  --color auto|always|never

pkglint explain PB101          # one rule's docs, an example, and how to fix or suppress it
pkglint --rules                # every rule

Suppressing findings

# pkglint: ignore=PB204
go build -o "$pkgname" .

A directive covers its own line and the next. To adopt pkglint on an existing package without fixing everything at once, run --add-ignores once. Directives that stop matching a finding are flagged and removed by --fix, so a fixed problem can't stay silenced if it comes back.

Auto-fixing

--fix rewrites what it can and prints every change. Run it with --diff to preview. Safe fixes keep the build's behavior or restore a security default. Unsafe fixes, such as upgrading http:// to https:// or adding --locked to cargo, change what the build does, so review them. A fix that can't see the whole picture is skipped rather than half-applied. For findings without a mechanical fix, pkglint prints a hint like updpkgsums or makepkg --printsrcinfo instead.

pkglint --rules and the rule reference show which rules each flag fixes.

Build and validate

The built-package rules (PB8xx) need a built package:

pkglint build ~/pkgbuilds/somepkg

This lints the PKGBUILD, runs makepkg, and then lints the archive it produces. pkglint build --fix also fixes PKGBUILD issues found only in the build output, such as a linked library missing from depends.

This is the only pkglint command that runs PKGBUILD code. It refuses to build when the static findings reach --fail-on, and always on a critical one. --force overrides the refusal. Nothing in the PKGBUILD can talk its way past that check.

How the build is isolated, and what you can change:

• The gate ignores the file's own # pkglint: ignore= directives. A curl | bash with ignore=PB304 above it is still refused. The printed report still honors them.
• makepkg flags and words that would build or source a different file (-p, -D, --config, BUILDFILE=, PKGDEST=, BUILDDIR=, …) are rejected, and a file argument must be the PKGBUILD itself.
• The packaging tree is left untouched: archives go to a temporary PKGDEST (use --keep <dir> to keep them), and the PKGBUILD is read-only during the build.
• Sources are cached in ${XDG_CACHE_HOME:-~/.cache}/pkglint/sources and the build happens under $TMPDIR. Set $SRCDEST or $BUILDDIR to move either.
• Dependencies are not installed and nothing is signed, so the hook never prompts for a password. Pass -- -s (or --makepkg-arg=-s in pre-commit args:) to install dependencies. In a container, pkglint intercepts -s: makepkg gets no sudo there. pkglint reads the dependency lists from the PKGBUILD statically and installs them as root with pacman -Syu before the package directory is copied in. It refuses a PKGBUILD whose lists cannot be read without running it, for example lists built by a command substitution, eval, source, or conditional assignment. For those, use an image with the dependencies already installed.
• Without makepkg on the host, or with --docker/--image, the build runs in a container ($PKGLINT_BUILD_IMAGE, $PKGLINT_BUILD_RUNNER = docker or podman). The container is a convenience, not a sandbox. The PKGBUILD's code still runs, and you are trusting the image.
• To lint a directory named build, write pkglint ./build.

Rules

Run pkglint explain <rule> or see the rule reference for each rule's details.

License

GPLv3. See LICENSE.