PKG-VERSION(8)

📦 version 2.7.5, in nixos 26.05, nixpkgs unstable

💅 pkg version — bestie's guide to checking your package versions ✨

okay so, pkg version is literally the manual page for the pkg version command. It lives in the System Manager's Manual, and it's about to make checking your installed packages against available ones feel like a whole vibe. no cap, this is the glow-up your package database has been waiting for. 🫶

🌸 SYNOPSIS 🌸

pkg version [-IPR] [-hoqvU] [-l limchar] [-L limchar] [-Cegix pattern]
    [-r reponame ...] [-O origin | -n pkgname] [index]
pkg version -t version1 version2
pkg version -T pkgname pattern

pkg version [--{index,ports,remote}]
    [--{help,origin,quiet,verbose,no-repo-update}] [--like limchar]
    [--not-like limchar]
    [--{case-sensitive,exact,glob,case-insensitive,regex} pattern]
    [--repository reponame ...] [--match-origin origin] [index]
pkg version --test-version version1 version2
pkg version --test-pattern pkgname pattern

like, that's the whole shape of it. three main modes, a million combo flags, and honestly? she ate. 💅

🦋 DESCRIPTION 🦋

pkg version is used for generating a report of packages installed by pkg(8). think of it as a little spreadsheet of your installed stuff, compared against whatever source you point it at. main character energy for your package database, lowkey.

The database of available packages and versions to compare against the installed packages may be chosen by specifying one of -P, -R or -I or by setting VERSION_SOURCE in pkg.conf(5). If you don't specify, she's got a whole default order and it's giving very "we've planned ahead, bestie":

  • if the ports index file exists, it's used (-I)
  • otherwise, if a ports tree exists, that's used to compare versions (-P)
  • failing both of those, the repository catalogue is used (-R)

When -I is used, versions of installed packages will be compared to the versions listed in the file argument index, or if that's not given explicitly, in the default ports index file — typically located as /usr/ports/INDEX-N, where N is the OS major version number. slay, very specific. 🎀

When -R is used, package repository catalogues will be automatically updated whenever pkg version is run by a user ID with write access to the package database. unless that's disabled by the -U flag, or by setting REPO_AUTOUPDATE to NO in pkg.conf(5). so like, yes she'll refresh herself, but only if you have the permissions and haven't told her not to. boundaries. iconic.

When comparing package versions the package name and a comparison character are printed. and these little characters are the whole vibe check, so memorize them:

  • = — The installed version of the package is current. 💚
  • < — The installed version of the package is older than the current version.
  • > — The installed version of the package is newer than the current version. This situation can arise with an out of date index file, or when testing new ports. 💀
  • ? — The installed package does not appear in the index. This could be due to an out of date index or a package taken from a PR that has not yet been committed. 🙈
  • ! — The installed package exists in the index but for some reason, pkg version was unable to compare the version number of the installed package with the corresponding entry in the index. not me trying to compare and failing, embarrassing.

✨ OPTIONS ✨

The following options are supported by pkg version. buckle up bestie, it's a list:

  • -C, --case-sensitive — Make the standard or the regular expression (-x) matching against pkg-name case sensitive. so like, Foo and foo are NOT the same anymore. respect the case.
  • -h, --help — Displays usage information. the "help me help you" button. 🫶
  • -I [index], --index [index] — Use index file for determining if a package is out of date. If no index file name is specified, uses the default index file. This is the default, if the index file exists. she loves a default moment.
  • -P, --ports — Use ports for determining if a package is out of date. This is the default if the index file is not present and a ports tree exists. The tree used can be overridden by PORTSDIR, see pkg.conf(5) for more information. port tree era.
  • -R, --remote — Use repository catalogue for determining if a package is out of date. This is the default if neither the ports index nor the ports tree exists. remote queen behavior. 👑
  • -U, --no-repo-update — Suppress the automatic update of the local copy of the repository catalogue from remote. This only has any effect in combination with the -R option. Automatic repository catalogue updates are only attempted when the effective UID of the process has write access to the package database. Otherwise they are silently ignored. so if you don't have write access, they just don't happen and nobody makes a thing of it. silent treatment, but make it permissions.
  • -r reponame, --repository reponame — Compare installed package versions to packages available from the named repository only. This option can be specified multiple times to use several repositories. Packages will be compared against the named repositories only, irrespective of the configured “enabled” status from repo.conf. By default, catalogues for all enabled repositories are used for version comparisons. Implies -R. so like, you can be picky about which repo she checks. queen of boundaries. 💅
  • -o, --origin — Display package origin, instead of package name. sometimes you want the receipts, not just the name. 🧾
  • -q, --quiet — Be quiet. Less output will be produced. shhh. no extra commentary. (i could never, but okay.)
  • -v, --verbose — Be verbose. the opposite of quiet. she's spilling everything. 🗣️
  • -l limchar, --like limchar — Display only the packages which status flag matches the one specified by limchar. so like, only show me the = ones, or only the ? ones. filter queen.
  • -L limchar, --not-like limchar — Does the opposite of -l flag. Displays the packages which status flag does not match the one specified by limchar. the "not her" filter. 🙅‍♀️
  • -i, --case-insensitive — Make the exact (-e) or regular expression (-x) matching against pattern case insensitive. This is the default, unless modified by setting CASE_SENSITIVE_MATCH to true in pkg.conf. so like, she's chill about case by default. lowercase bestie.
  • -x pattern, --regex pattern — Only display the packages that match the regular expression. Uses the "modern" or "extended" syntax of re_format(7). regex girlies rise. 🔥
  • -g pattern, --glob pattern — Only display the packages that match the glob expression. wildcards, but make it fashion. 🌈
  • -e string, --exact string — Only display the packages that exactly match the string. no vibes, only precision. 🎯
  • -O origin, --match-origin origin — Display only the packages which origin matches origin. origin story only.
  • -n pkgname, --match-name pkgname — Display only the packages which name matches pkgname. name drop, but filtered.
  • -t version1 version2, --test-version version1 version2 — Test a pair of version number strings and exit. The output consists of one of the single characters = (equal), < (right-hand number greater), or > (left-hand number greater) on standard output. This flag is mostly useful for scripts or for testing. so like, she's comparing two versions and giving you one little character of a verdict. minimal, but make it useful. 💖
  • -T pkgname pattern, --test-pattern pkgname pattern — Compare pkgname against shell glob pattern and set exit code accordingly. -T can also be used in filter mode: When one of the arguments is -, standard input is used, and lines with matching package names/patterns are echoed to standard output. filter mode is giving pipe energy and honestly? we love a stdin moment.

🌸 ENVIRONMENT 🌸

The following environment variables affect the execution of pkg version. See pkg.conf(5) for further description. they're like the backstage crew of this whole operation:

  • CASE_SENSITIVE_MATCH
  • INDEXDIR
  • INDEXFILE
  • PKG_DBDIR
  • PORTSDIR

The default index file is searched for in INDEXDIR, or if that is not set, PORTSDIR. INDEXFILE is the name of the index relative to that directory. If INDEXFILE is not set, the default file name is INDEX-N where N is the OS major version number. so like, she's got a whole search order and naming convention and it's very organized. 🎀

🦋 FILES 🦋

See pkg.conf(5). that's it. that's the file section. short and slay.

✨ EXAMPLES ✨

The following is a typical invocation of the pkg version command, which checks the installed packages against the local ports index file:

% pkg version -v

The command below generates a report against the versions in the repository catalogue:

% pkg update
% pkg version -vR

The following lists packages needing upgrade, compared to the repository catalogue:

% pkg update
% pkg version -vRL=

The following command compares two package version strings:

% pkg version -t 1.5 1.5.1

like, these are the starter pack. go forth and version-check. 💅✨

🫶 SEE ALSO 🫶

pkg_create(3), pkg_printf(3), pkg_repo_create(3), pkg_repos(3), pkg-keywords(5), pkg-lua-script(5), pkg-repository(5), pkg-script(5), pkg-triggers(5), pkg.conf(5), pkg(8), pkg-add(8), pkg-alias(8), pkg-annotate(8), pkg-audit(8), pkg-autoremove(8), pkg-check(8), pkg-clean(8), pkg-config(8), pkg-create(8), pkg-delete(8), pkg-fetch(8), pkg-help(8), pkg-info(8), pkg-install(8), pkg-key(8), pkg-lock(8), pkg-plugins(8), pkg-query(8), pkg-register(8), pkg-repo(8), pkg-repositories(8), pkg-rquery(8), pkg-search(8), pkg-set(8), pkg-shell(8), pkg-shlib(8), pkg-ssh(8), pkg-stats(8), pkg-triggers(8), pkg-unregister(8), pkg-update(8), pkg-updating(8), pkg-upgrade(8), pkg-which(8)

the whole friend group, basically. go read them too, iykyk. 📚

bestie, this page is from Debian, dated July 7, 2024, and it's the PKG-VERSION(8) manual page. that's the whole sign-off. stay slay, stay versioned, and may all your comparisons return = 💖✨🎀
📦 where this page comes from