PKG-CREATE(8)

📦 version 2.7.5, in nixos 26.05, nixpkgs unstable

🦋 pkg-create(8) — the manual page, but make it bestie-friendly 🎀

okay so like, hi. this is pkg-create(8) from the System Manager's Manual, and it's genuinely the girlboss of the pkg suite. she makes packages. she's iconic. let's get into it 💅

✨ NAME ✨

pkg create — a utility for creating software package distributions 🫶

🌸 SYNOPSIS 🌸

like, here's the whole vibe chart. pick your lane, bestie:

pkg create [-enqv] [-f format] [-l level] [-o outdir] [-p plist]
    [-r rootdir] [-t timestamp] [-T threads] -m metadatadir
pkg create [-enqv] [-f format] [-l level] [-o outdir] [-r rootdir]
    [-t timestamp] [-T threads] -M manifest
pkg create [-egnqvx] [-f format] [-l level] [-o outdir] [-r rootdir]
    [-t timestamp] [-T threads] pkg-name ...
pkg create [-enqv] [-f format] [-l level] [-o outdir] [-r rootdir]
    [-t timestamp] [-T threads] -a

pkg create [--expand-manifest] [--no-clobber] [--quiet] [--verbose]
    [--format format] [--level level] [--out-dir outdir] [--plist plist]
    [--root-dir rootdir] --metadata metadatadir
pkg create [--expand-manifest] [--no-clobber] [--quiet] [--verbose]
    [--format format] [--level level] [--out-dir outdir]
    [--root-dir rootdir] --manifest manifest
pkg create [--expand-manifest] [--{glob,no-clobber,regex}] [--quiet]
    [--verbose] [--format format] [--level level] [--out-dir outdir]
    [--root-dir rootdir] pkg-name ...
pkg create [--expand-manifest] [--no-clobber] [--quiet] [--verbose]
    [--format format] [--level level] [--out-dir outdir]
    [--root-dir rootdir] --all

yes, both the short-flag version and the long-flag version, because she contains multitudes 💖

👑 DESCRIPTION 👑

so. pkg create is the utility you use to create packages out of binaries and other files that are installed on your computer. that's the whole job. main character energy, no notes.

Route one: package tarballs can be created from the files of a previously installed package, using metadata from the local package database. and the slay part? any number of packages may be created in one invocation of this style. not one. not two. as many as you want 🔥

Route two: alternatively, a single package can be created from an arbitrary selection of files on your system — but this requires a metadatadir and, optionally, a plist to be supplied. the package name will be derived from the +MANIFEST file, which must be contained within the metadatadir, or passed as the argument to -M.

and then, packages created this way can be distributed and subsequently installed on other machines using the pkg add command. so you're literally making a little care package for another machine. we love a gift-giver 🌈💝

✨ OPTIONS ✨

the following options are supported by pkg create. all of them. we're not skipping any, bestie, i know you'd never forgive me:

-M manifest, --manifest manifest — read all of the package metadata from the manifest file. this is exactly the same format as +MANIFEST mentioned above, but any file name can be used, and no other file will be used to read package metadata from. if specified, only a single package will be created. this option is incompatible with the -m, -a, -g or -x options 🚫
-T threads — threads represents the number of threads to use during the compression of the archive. set it to "0" or "auto" to have pkg create detect the number of CPUs and use one thread per CPU. let her cook in parallel, periodt 💅
-a, --all — create package tarballs from all packages installed on your system. this option is incompatible with the -g, -x or -m metadatadir options. it's giving "all or nothing" 🦋
-e, --expand-manifest — the manifest contained in pkg will be expanded to readable UCL format. so you can actually read it, bestie, instead of squinting 😭
-f format, --format format — set format as the package compression format. it can be one of tzst, txz, tbz, tgz or tar, which are currently the only supported formats. if an invalid format, or no format, is specified, then tzst is assumed. (the .pkg extension is used for all compression types — yes, all of them, don't come for her 🎀)
-h, --hash — append a short hash of the package contents to the package filename. this can be used in combination with -s to create symlinks between the hashed and regular filenames 🔗
-g, --glob — interpret pkg-name as a shell glob pattern and create a package only for installed binaries whose name match this pattern. this option is incompatible with the -a, -x or -m metadatadir options ✨
-l level, --level level — set the compression level for created packages. it can be any valid numeric compression level you might specify to the underlying compression format. additionally, level may be one of the special words “fast” or “best”. if level is one of these special words, the fastest or slowest compression level, respectively, for the specified compression format, is used. lowkey the “best” one takes a minute, so hydrate 💧
-m metadatadir, --metadata metadatadir — specify the directory containing the package manifest, +MANIFEST, and optionally two other files: one containing a message to be displayed on package installation, +DISPLAY, and another containing the description for the package, +DESC. if specified, only a single package will be created. +DISPLAY and +DESC are not required; the +MANIFEST file can contain all the required information needed to build a package. this option is incompatible with the -M, -a, -g or -x options 👑
-n, --no-clobber — do not overwrite already existing packages. respectful. we stan boundaries 🫶
-o outdir, --out-dir outdir — set outdir as the output directory. if this option is not given, all created packages will be saved in the current directory. so like, look around before you're like "where did my package go" 🙈
-p plist, --plist plist — specify some package metadata using the legacy plist format from pkg_add(1), commonly found in pkg-plist files in the ports tree. metadata from the plist file, if specified, will take precedence over any equivalents from the metadatadir. only has any effect when used with metadatadir. see “PLIST FORMAT” for details. yes she's legacy, yes she still eats 💀
-q, --quiet — force quiet output. this is the default, unless PKG_CREATE_VERBOSE is set to yes in pkg.conf. so if you're wondering why she's so chill by default, that's why 🤫
-r rootdir, --root-dir rootdir — rootdir specifies the top-level directory to be treated as the root of the filesystem hierarchy containing the package files. file paths in generated packages will be relative to rootdir. this allows a package to be generated from content offset from its intended final location, which allows a package to be built without disturbing similar content already on the system. if unspecified, the default is effectively /, the actual root directory 🏠
-t timestamp, --timestamp — set the timestamp of the files within the archive ⏰
-v, --verbose — force verbose output, the opposite of --quiet. she's chatty now 💬
-x, --regex — like -g, but interpret pkg-name as a regular expression using the "modern" or "extended" syntax described in re_format(7). this option is incompatible with the -a, -g or -m metadatadir options. regex girlies rise 🌸

⚠️ okay so notice how many of these say "incompatible with" each other? that's not a suggestion, bestie. if you pair them up anyway she's not gonna have a good time and neither are you. pick one lane 💀

🎀 MANIFEST FILE DETAILS 🎀

this is the part where we get into the +MANIFEST file's fields, one by one. it's giving "character sheet for your package." let's go 🔥

`name` pkg-name

this entry sets the package's name to pkg-name. among other things, this name is used — with the version and the origin of the concerned package — to identify a dependency. so like, she's on the group chat roster 📋

`version` pkg-version

this entry sets the package's version to pkg-version. gotta know which era of the package you're dealing with ✨

`origin` pkg-origin

this entry sets the package's origin to pkg-origin. this is a string of the form category/port-dir which designates the port this package was built from 🧚

`comment` comment-string

comment-string is a one-line description of this package. it is the equivalent of the COMMENT variable for a port — not a way to put comments in a +MANIFEST file. i know. i know. read that twice. it's not that kind of comment 💀

`desc` description

description is a longer description of the package. it is the equivalent of the pkg-descr file for a port. it may be one to a few paragraphs. for example:

desc = <<EOD
   This is a longer description of the package.
   It can span multiple lines.

   It can also span multiple paragraphs.
EOD

see, she can be wordy. it's fine. it's a vibe 🌈

`arch` cpu-type

the architecture of the machine the package was built on. cpu-type takes values like x86, amd64… 💻

`www` url

the software's official website. link her 🔗

`maintainer` mail-address

the maintainer's mail address. someone has to be responsible for her, and it's this person 📮

`prefix` path-prefix

the path where the files contained in this package are installed (usually /usr/local) 🏡

`flatsize` size

the size the files contained in this package will occupy on your system once uncompressed. this value does not take into account files stored in the package database. so like, it's not the whole story, just the flat part 📦

`deps` dep-name dep-origin dep-version

associative array of package dependencies, keyed on dep-name and with values version dep-version and origin dep-origin. for example:

"deps" : {
   "pstree" : {
      "version" : "2.36",
      "origin" : "sysutils/pstree"
   },
   "cdiff" : {
      "version" : "0.9.6.20140711,1",
      "origin" : "textproc/cdiff"
   },
},

her little friend group 🫶 every package needs her girls

`conflict` pkg-glob

flag this package as incompatible with the one designated by pkg-glob. conflicting packages cannot be installed on the same system, as they may contain references to the same files 🚩

⚠️ not "can't be installed in the same second," bestie — cannot be installed on the same system. full stop. do not test this 🙈

`option` option-name option-value

set the option option-name to the value option-value 🎛️

`file` sha256-hash path

file entries list files included in the package. if the file is a regular one, such an entry contains its sha256 digest along with its path. if a packaged file is a link, you must use this entry's other form, as described below 🔍

`file` `-` path

same as above but for file links. the sha256 hash is replaced with a - (dash). cute, right? it's a placeholder slay ✨

`dir` path

mimics the file entry, but for directories 📁

🌸 PLIST FORMAT 🌸

Okay bestie, so the plist format is literally just a sequential list of lines, and any of those lines can have a keyword slapped on the front. A keyword always starts with an @. Any line that doesn't start with a keyword? That's a path to a file, periodt. If it starts with a / it's an absolute path; otherwise the file is relative to PREFIX.

Keyword lines look like this:

@keyword line

Here's the full icon lineup of available keywords 👑

@cwd [directory] — points the internal directory pointer at directory. Every filename after this gets read as relative to that directory.
@mode mode — sets the default permission for all the files extracted after it to mode. The format is the exact same one the chmod command uses. Call it with no argument and you're back to the default permissions (aka the mode the file had while it was being packed).
@owner user — sets the default ownership for all subsequent files to user. No argument? Back to the default ownership, which is root.
@group group — sets the default group ownership for all subsequent files to group. No argument? Back to the default group ownership, which is wheel.
@comment string — this line gets ignored when packing. Just vibes, no function ✨
@dir name — declares name as a directory to be deleted at deinstall time. Ngl, most directories made by a package installation get deleted automatically on deinstall, so you only need this directive for empty directories or directories outside of PREFIX. These directives should live at the end of the package list. And heads up: if the directory isn't empty, a warning gets printed and the directory is not removed. Also — subdirectories should be listed before their parent directories 💅
@include name — pulls the name plist file into the plist currently being parsed. The name gets opened relative to the main plist file being parsed. ⚠️ Note: only one level of @include is allowed, bestie, don't try to stack 'em.

🌈 ESCAPE SEQUENCES 🌈

This heading shows up in the page and that's… all it does in the source. No entries listed under it, so there's nothing more to spill here 🙈

🦋 ENVIRONMENT 🦋

These environment variables affect the execution of pkg create. Peep pkg.conf(5) for the fuller description.

PKG_DBDIR
PLIST_KEYWORDS_DIR
PORTSDIR
SOURCE_DATE_EPOCH — sets the timestamp for every single file in the archive to the one you specify in this environment variable ⏰

🎀 FILES 🎀

See pkg.conf(5).

🍓 EXAMPLES 🍓

Create package files for installed packages:

% pkg create -a -o /usr/ports/packages/All

Create a package file for pkg:

% pkg create -o /usr/ports/packages/All pkg

👑 SEE ALSO 👑

The whole friend group, no cap:

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-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-version(8), pkg-which(8)

That's the whole page, bestie, you ate it up 💅 This edition ships from the Debian flavor of PKG-CREATE(8), dated December 13, 2025 — go forth and pack some packages 🫶✨

📦 where this page comes from

nixos 26.05: pkg 2.7.5
nixpkgs unstable: pkg 2.7.5
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

PKG-CREATE(8)

🦋 pkg-create(8) — the manual page, but make it bestie-friendly 🎀

✨ NAME ✨

🌸 SYNOPSIS 🌸

👑 DESCRIPTION 👑

✨ OPTIONS ✨

🎀 MANIFEST FILE DETAILS 🎀

name pkg-name

version pkg-version

origin pkg-origin

comment comment-string

desc description

arch cpu-type

www url

maintainer mail-address

prefix path-prefix

flatsize size

deps dep-name dep-origin dep-version

conflict pkg-glob

option option-name option-value

file sha256-hash path

file - path

dir path