Skip to content

Package.toml Format

Target audience: Maintainers Goal: Full reference for the package.toml metadata format used in package definitions.

[package]

Field Required Description
name yes Package name (e.g. "curl").
version yes, unless version_from is set Version string (e.g. "8.9.1").
version_from yes, for pallets Inherits version from another package. Format: "core-python".
description yes Brief description.
license yes SPDX license expression (e.g. "MIT", "GPL-2.0-or-later AND LGPL-2.1-or-later").
website no Homepage or project URL.
subpackages no List of subpackage names included with this package.

[sources.*]

The section name typically matches the package name (e.g. [sources.curl]).

Field Required Description
hash yes SHA-256 hash of the source archive (hex string).
format no Archive format ("tar.gz", "tar.xz", etc.). Defaults to an empty string.
file no Filename template with placeholders. Falls back to the mirror-derived filename if omitted.
version no Source version. Inherits from [package] version if omitted.
git_sha no Git commit SHA for traceability. Passed to the Containerfile as ARG GIT_SHA.
mirrors yes Array of download URLs with placeholders.

Placeholder Reference

Templates in file and mirrors support these placeholders:

Placeholder Example (X.Y.Z) Description
{version} X.Y.Z Full version string
{version_major} X Major version component
{version_major_minor} X.Y Major.minor
{version_dash} X-Y-Z Version with dashes replacing dots
{version_strip_suffix} X.Y.Z Version with pre-release suffix stripped (from X.Y.Z-rc.1)
{version_under} X_Y_Z Version with underscores replacing dots
{format} tar.gz Archive format extension
{file} Computed filename Result of file template expansion (only usable in mirrors)

Examples

Standard Package

[package]
name = "curl"
version = "8.9.1"
description = "Command line tool and library for transferring data with URLs"
license = "curl"
website = "https://curl.se/"

[sources.curl]
hash = "f292f6cc051d5bbabf725ef85d432dfeacc8711dd717ea97612ae590643801e5"
format = "tar.xz"
file = "curl-{version}.{format}"
mirrors = [ "https://curl.se/download/{file}" ]

Pallet Inheriting Version

[package]
name = "python"
version_from = "core-python"
description = "Runtime for building python packages"
license = "0BSD AND Apache-2.0"
website = "https://python.org/"

See Also