pkglint

A security-focused linter for Arch Linux packages.

$ pkglint ~/pkgbuilds/somepkg
somepkg: grade F, 3 finding(s)
  PKGBUILD:16:3: critical [PB304] a network download is piped straight into bash and executed
  PKGBUILD:11:1: error [PB101] remote source "http://..." has no checksum (SKIP): the download is never verified
  PKGBUILD:11:1: error [PB104] source "http://..." is fetched over unencrypted http:// with nothing verifying what arrives

1 package linted: 1 with findings
1 finding(s) fixable with --unsafe-fix

• Never runs the package. PKGBUILDs are parsed into a real bash syntax tree, not sourced, so quoting and line-continuation tricks that fool regex scanners don't work. Built packages are inspected without loading or executing anything in them.
• Checks what matters for trust: unverified sources, builds that fetch undeclared code, download-and-execute, writes outside the package, and persistence in install scripts.
• Covers namcap and makepkg too: namcap's PKGBUILD and built-package checks, plus makepkg's own build-breaking metadata errors, all in one report.
• Fixes what it can. --fix applies the safe rewrites, and --unsafe-fix applies the ones that change build behavior.

The AUR Report Card runs pkglint nightly over the official repositories and the AUR's most popular and recently updated packages.

Install

AUR

yay -S pkglint

PyPI

uv tool install pkglint

Go

go install github.com/jmelahman/pkglint@latest

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

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.