--- name: "package" section: "5" platform: "openbsd" package: "man" version: "8.0-current-20261101" release: "OpenBSD 8.0-current (2026-11-01)" platforms: ["openbsd"] url: "https://new.carta.tech/package/5" --- # package(5) format for OpenBSD binary packages and packing-lists ## NAME **package**, **packing-list**, **plist** – format for OpenBSD binary packages and packing-lists ## DESCRIPTION Binary packages for OpenBSD can be created using [pkg\_create(1)](/pkg_create/1.md) and are usually manipulated using pkg\_add(1), [pkg\_mklocatedb(1)](/pkg_mklocatedb/1.md), or [pkg\_info(1)](/pkg_info/1.md). The basic underlying format is an archive following the ustar specification that can be handled with [tar(1)](/tar/1.md) and compressed using [gzip(1)](/gzip/1.md). Package names always end in “.tgz”; the file name itself should conform to [packages-specs(7)](/packages-specs/7.md). Note that the base distribution tarballs of OpenBSD (e.g. *baseXX.tgz*, *compXX.tgz*, ...) are not binary packages fit for pkg\_add(1). All types of archive contents can be present in a package, including files, directories, hardlinks, symlinks, fifos, block and character devices. In order to allow just-in-time extraction, packages always begin with a table of contents, named *+CONTENTS*, nicknamed **packing-list**( **plist** for short). This table of contents can be read using the API described in [OpenBSD::PackingList(3p)](/OpenBSD::PackingList/3p.md). All the remaining information in the archive should be referenced in the **packing-list**, including symlinks destinations, special permissions, and file owners( [pkg\_create(1)](/pkg_create/1.md) and pkg\_add(1) actually enforce this). See [pkg\_create(1)](/pkg_create/1.md) for annotation details. This table of contents is always followed by a few special files, some of which are optional: the package description (+DESC), a display message (+DISPLAY), etc. The basic ustar format has some limitations with respect to file names. Packages now use the "extended record specification" (header type x) for long links and long file names. Other extended ustar headers are currently recognized, but not supported. Starting with OpenBSD 5.5, the compressed archive may be composed of several [gzip(1)](/gzip/1.md) archives concatenated together. [gzip(1)](/gzip/1.md) doesn't mind, and [tar(1)](/tar/1.md) is happy as long as the uncompressed stream is sane. This allows for faster signing and better rsync properties. Starting with OpenBSD 5.6, tarballs are stored "out-of-order": each archive entry will match an entry in the **packing-list** (and all file-like entries will be matched), but the order will be adjusted so that most recently changed files come first, in order to allow faster updates. Starting with OpenBSD 5.7, by default, timestamps are stored directly in the **packing-list** as **@ts** annotations. The files in the archive will have a null timestamp. The combination of the LRU archive order, null timestamps and compression in fixed chunks starting from the end, means a substantial amount of data doesn't change from snapshot to snapshot, thus reducing the pressure on mirroring bandwidth. ## PACKING LIST ANNOTATIONS User annotations are described in [pkg\_create(1)](/pkg_create/1.md). The following annotations are automatically inserted during package creation and installation: - **@arch** *arches* List of architectures for which this package is intended. This corresponds to **-A** *arches* of [pkg\_create(1)](/pkg_create/1.md) - **@comment** **pkgpath=path** **ftp=yes/no** Historical accident. This specific comment encodes the actual **-D** *FULLPKGPATH*, and **-D** *FTP* arguments to [pkg\_create(1)](/pkg_create/1.md). - **@depend** *pkgpath*: *pkgspec*: *default* Record a dependency declared using the option **-P** of [pkg\_create(1)](/pkg_create/1.md). - **@digital-signature** *signify2*: *date*: *external* Record the date of signature of a package, synthesized by pkg\_add(1) from [signify(1)](/signify/1.md) output. - **@link** *name* Added after a file entry by **package** to record that the entry is actually a hard link. - **@localbase** *base* Used internally to record the settings of **-L** option. - **@name** *pkgname* Set the name of the package. This name is potentially different than the name of the file it came in, and is used when keeping track of the package for later deinstallation. [pkg\_create(1)](/pkg_create/1.md) will derive this field from the package file name. - **@option** *name* Some options are automatically inserted/modified by the package tools: - *always-update* [pkg\_create(1)](/pkg_create/1.md) will complete the option line with a sha256 digest of the whole **packing-list** encoded in base64. - *firmware* Set by [fw\_update(8)](/fw_update/8.md) to trigger firmware-specific handling. In particular, firmware is hidden from normal updates. - *manual-installation* Record that a package has been explicitly installed by the user, and not as a result of a dependency look-up. Refer to pkg\_add(1)'s **-a** option for details. - **@sha** Added after a file entry by [pkg\_create(1)](/pkg_create/1.md) to record the files's cryptographic checksum, as a sha256 digest encoded in base64. - **@signer** Record the signing key for a package, synthesized by pkg\_add(1) from [signify(1)](/signify/1.md) output. - **@size** Added after a file entry by [pkg\_create(1)](/pkg_create/1.md) to record a file size. - **@symlink** *name* Added after a file entry by [pkg\_create(1)](/pkg_create/1.md) to record that the entry is actually a symbolic link. - **@url** Original location of the package, synthesized by pkg\_add(1) during installation. - **@ts** *timestamp* Added after a file entry to record the actual file timestamp, instead of storing it as tarball meta-info. The package tools read and process that annotation correctly, whereas [tar(1)](/tar/1.md) will only see files dated from the epoch. - **@version** *number* Record a global (system) version number for the package. This is built adding together **-V** options from [pkg\_create(1)](/pkg_create/1.md), and triggers updates when it changes. - **@wantlib** *libspec* Record a library requirement declared using the option **-W** of [pkg\_create(1)](/pkg_create/1.md). Note that most of these annotations cannot be added manually, as [pkg\_create(1)](/pkg_create/1.md) will error out. ## PACKAGE SIGNATURES All information within a package is checksummed, using SHA256 since OpenBSD 4.4. During creation and installation, meta-information, such as file owners and permissions, are also checked: any important stuff that isn't recorded in the **packing-list** is an error. Starting with OpenBSD 6.1, [signify(1)](/signify/1.md) **-zS** [gzip(1)](/gzip/1.md) header signatures are the only supported format. This allows for ‘just-in-time’ signature checking, as the binary data is checked in 64K bytes long chunks. ## SEE ALSO pkg\_add(1), [pkg\_create(1)](/pkg_create/1.md), [pkg\_info(1)](/pkg_info/1.md), [pkg\_sign(1)](/pkg_sign/1.md), [packages(7)](/packages/7.md), [packages-specs(7)](/packages-specs/7.md) ## STANDARDS Packages are valid gzip'ed ustar archives that can be extracted using [tar(1)](/tar/1.md). In particular, hardlink names should be valid, and all items will extract to different names. However, it may be a bit difficult to make sense of the package contents without peeking at the **packing-list**.