PKG-SEARCH(8)

📦 version 2.7.5, in nixos 26.05, nixpkgs unstable

💅 pkg-search(8) — the System Manager's Manual page, but make it group chat 💅

✨ NAME ✨

pkg search — search package repository catalogues 💖

🔍 SYNOPSIS 🔍

okay so here's the whole shape of it, bestie, no cap:

       pkg search [-U] [-r reponame ...] [-S search] [-L label]
           [-Q query-modifier] [-Cegix] pattern
       pkg search [-cDdfopqRsU] [-r reponame ...] [-Cegix] pattern

       pkg search [--no-repo-update] [--repository reponame ...]
           [--search search] [--label label] [--query-modifier query-modifier]
           [--{case-sensitive,exact,glob,case-insensitive,regex}] pattern
       pkg search [--{comment,description,depends-on,full,origins,prefix}]
           [--{quiet,raw,size,no-repo-update}] [--repository reponame ...]
           [--{case-sensitive,exact,glob,case-insensitive,regex}]
           [--raw-format format] pattern

💖 DESCRIPTION 💖

pkg search is the whole vibe for searching package repository catalogues. You can match packages that are available for installation by their name, by name and version, by origin, or by text inside the package comments or package descriptions. The output defaults to showing the field that got matched by the search term, but literally any of the searchable fields can be displayed. You can also modify the output so it shows a bunch of other package data available from the repository catalogues. Iconic.

Package repository catalogues get automatically updated whenever pkg search is run by a user ID with write access to the package database — unless you disable it with the -U flag or set REPO_AUTOUPDATE to NO in pkg.conf(5). Not me explaining this twice, it's just important.

Package repositories are defined in the pkg.conf file or by creating repository definitions in /usr/local/etc/pkg/repos. See pkg.conf(5) for details.

🎀 OPTIONS 🎀

The following options are supported by pkg search, and yes we're going through every single one:

  • -C, --case-sensitive — makes the exact (-e) or the regular expression (-x) matching against pkg-name case sensitive. Capital letters matter now, bestie 🔥
  • -c, --comment — searches for packages with comment text matching pattern. Equivalent to -S comment.
  • -D, --description — searches for packages with description text matching pattern. Equivalent to -S description.
  • -d, --depends-on — displays the list of packages depended on by each matched package. Equivalent to -Q depends-on.
  • -e, --exact — says pattern should be an exact match against the search field. No fuzzy business.
  • -f, --full — shows “full” information about the package. Equivalent to -Q full. It's giving everything-at-once energy ✨
  • -g, --glob — treats pattern as a shell globbing expression. The glob pattern must match the entire field being searched. Whole field or it doesn't count 💅
  • -i, --case-insensitive — makes 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.
  • -L label, --label label — selects which identifying label is printed for each matched package, unless -q is used. Several different fields from the repository catalogue database may be used to search on, or to generate the label, as indicated by the label argument. See the “Search and Label Options” section for details. If unspecified, label is set to the same as the value searched via the -S search option.
  • -o, --origins — lists packages by origin for each package matching pattern. Equivalent to -L origin.
  • -p, --prefix — displays the package installation prefix for each matched package. Equivalent to -Q prefix.
  • -q, --quiet — be “quiet”. Produces less output. In particular, it does not show an identifying label field for each package. Shhh 🤫
  • -Q query-modifier, --query-modifier query-modifier — modifies the query output by adding an additional field to the result. Multiple fields can be added by using additional -Q query-modifier flags. See the “Output Modifier Options” section for details.
  • -r reponame, --repository reponame — searches for packages from only the named repository. This option can be specified multiple times to use several repositories. Packages will be searched from the named repositories only, irrespective of the configured “enabled” status from repo.conf. By default, catalogues for all enabled repositories are searched.
  • -R, --raw — displays the full manifest (raw) from the matching packages. Raw and unfiltered, like my group chat receipts 💀
  • -S search, --search search — specifies the field to search the repository catalogue on. If unspecified, it searches on pkg-name unless the search term contains a / character, when it searches on port origin. Output will be sorted in order of the search field. See the “Search and Label Options” sections for more details.
  • --raw-format format — chooses the format of the raw output. The format can be: json, json-compact, ucl, yaml (default). Pick your fighter 🎀
  • -s, --size — displays the installed size of matched packages. Equivalent to -Q size.
  • -U, --no-repo-update — suppresses the automatic update of the local copy of the repository catalogue from remote. 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.
  • -x, --regex — treats pattern as a regular expression according to the “modern” or “extended” syntax of re_format(7). This is the default. Matches any substring of the search field unless explicit beginning or ending anchor terms are used.

🧚 Search and Label Options 🧚

Okay so these database fields (or composites of several fields) can be used both for searching for a match to the given pattern and as identifying labels for the block of output for each package:

  • comment — the one line comment field describing the port, derived from the COMMENT variable in the port's Makefile. When chosen as a label option, the output format will additionally include the package name, equivalent to -L pkg-name -Q comment. When chosen as a search option, only the comment field is used for sorting the output.
  • comment-description — both the one line comment and the multi-line description fields. When chosen as a search option, a package will match if pattern is found in either field. The output format will include the package name, comment and description. Results are sorted by comment. This option is only available as a search field (-S), not as a label option (-L).
  • description — the multi-line package description from the pkg-descr file in the port. This does include the WWW URL reference, if any, from that file. When chosen as a label option, the output format will additionally include the package name, equivalent to -L pkg-name -Q description. When chosen as a search option, only the description field is used for sorting the output.
  • name — the name of the package, derived from the PORTNAME variable in the port's Makefile.
  • origin — the port origin, in the format category/port, that the package was compiled from.
  • pkg-name — the package name in the format name-version. The same as the PKGNAME variable in the port's Makefile.

Any unambiguous prefix of the label name may be used on the command line. Thus -Sd, -S descr and -S description are all equivalent. Love that for us 🫶

🌈 Output Modifier Options 🌈

These add extra data from the repository catalogue to print for each matched package. Multiple output modifiers can be combined. Where more than one output field is required — either because multiple -Q query-modifier options were given, or one or more -Q query-modifier option was combined with the -L comment or -L description options — then each output field will be tagged with the field name. Periodt.

  • annotations — arbitrary text in tag-value format that can be added to any package. Cute little sticky notes for packages 💜
  • arch — the architecture string indicating what OS version and CPU architecture the package is suitable for. For example, freebsd:9:x86:64 indicates a package suitable for FreeBSD 9.x running on an amd64 processor, while freebsd:* indicates an architecture independent package suitable for any version of FreeBSD.
  • categories — all categories, real and virtual, that the underlying package belongs to, derived from the CATEGORIES variable in the port's Makefile.
  • comment — the one line comment field describing the port, derived from the COMMENT variable in the port's Makefile.
  • depends-on — the list of packages the named package depends on. Dependency packages are listed in the format name-version one per line. If the port has no dependencies, nothing will be output for this field, including suppressing the tag name when multiple output fields are requested.
  • description — the multi-line package description from the pkg-descr file in the port. This does include the WWW URL reference, if any, from that file.
  • full — shows a standard set of fields, equivalent to a combination of the name, version, origin, prefix, repository, categories, license, maintainer, www, comment, options, shared-libs-required, shared-libs-provided, annotations, size, pkg-size and descr fields, in that order. It's the whole fit check, bestie 👑
  • licenses — displays a list of all the licenses the package is released under on a single line. Where more than one license applies, indicate if the terms of all licenses should apply (&) or if one or more licenses may be selected out of those available (|).
  • maintainer — displays the maintainer's e-mail address.
  • name — displays the port name, which is derived from the PORTNAME variable in the port's Makefile.
  • options — displays a list of the port options and their state (on or off) when the package was built. If the package does not have any options to set, nothing will be output for this field, including suppressing the tag name when multiple output fields are requested.
  • pkg-size — displays the size of the compressed package tarball, i.e., how much would need to be downloaded from the repository.
  • prefix — displays the installation prefix for the package, usually /usr/local.
  • repository — displays the repository name and the corresponding base URL for the repository. For a default repository defined in pkg.conf.
  • required-by — shows every package in the repo that needs the named package as a dependency 🫶. These dependency packages come out in name-version format, one per line. And if literally nothing requires the named package? Then this field outputs nothing at all — and yes, it even suppresses the tag name when you asked for multiple output fields. Sneaky but true 💅.
  • shared-libs-required — if the package has dynamically linked FreeBSD ELF binaries in it, this lists every shared library those binaries need to run, except the ones from the base system. Small but important caveat: shared libraries for foreign binaries (like, Linux ones running under emulation) will not show up here, no cap. And if the package needs zero shared libraries, this field outputs nothing — tag name suppressed and everything, same deal as above when you're requesting multiple fields 🙈.
  • shared-libs-provided — if the package ships any shared libraries, this lists the library names, including the ABI version number if there is one 🎀. Lowkey a red flag moment here: a shared library — same ABI version or differing ones — may legitimately be provided by more than installed package, but it frequently indicates a problem. So like, don't panic, but do side-eye it 👀.
  • size — the total amount of filesystem space the package files will take up once they're unpacked and installed 📦.
  • url — the URL that would be used to download the package from the repository ⬇️.
  • version — the package version, which is derived from the PKGVERSION variable in the port's Makefile ✨.
  • www — the general URL, if any, for the project developing the software used in the package 🌐. This gets extracted from the pkg-descr file in the port.

Okay so shortcuts, because typing the whole thing is so much: any unambiguous prefix of the query modifier name may be used on the command line 💫. So -Qm, -Q maint and -Q maintainer are all equivalent — iconic, she's flexible. But you do need at least -Q si and -Q sh to distinguish size from shared-libs-required or shared-libs-provided, and you'll need at least -Q shared-libs-p to select shared-libs-provided unambiguously. Ambiguity is not the vibe 🫠.

🌍 ENVIRONMENT 🌍

These environment variables affect how pkg search runs, bestie. Peep pkg.conf(5) for the full description of each 🧚.

  • PKG_DBDIR — yep, that one 🗂️.
  • CASE_SENSITIVE_MATCH — and that one too 🔤.

📁 FILES 📁

See pkg.conf(5) 💖. That's the whole bit — go read it, iykyk.

🔗 SEE ALSO 🔗

A whole friend group of related pages, fr fr — go say hi to all of them 💜:

And that's a wrap, bestie!! 🦋✨ This lil masterpiece is from Debian, dated December 13, 2025, and it's the PKG-SEARCH(8) page 💅. Go search something iconic. Periodt. 🎀

📦 where this page comes from