Configuration Reference

Per-package Settings

Settings for individual packages can be placed in the overrides/settings/ directory. Files should be named using the canonicalized name of the package. For example flash_attn.yaml.

pydantic model fromager.packagesettings.PackageSettings

Package settings

build_dir: python
changelog:
    "1.0.1":
        - fixed bug
env:
    EGG: spam
download_source:
    url: https://egg.test
    destination_filename: new_filename
resolver_dist:
    sdist_server_url: https://sdist.test/egg
    include_sdists: true
    include_wheels: false
build_options:
    build_ext_parallel: False
    cpu_cores_per_job: 1
    memory_per_job_gb: 1.0
    exclusive_build: False
variants:
    cpu:
        env:
            EGG: spamalot
        wheel_server_url: https://wheel.test/simple
    rocm:
        pre_built: True
Fields:

  • annotations (collections.abc.Mapping[str, str] | None)

  • build_dir (pathlib.Path | None)

  • build_options (fromager.packagesettings._models.BuildOptions)

  • changelog (collections.abc.Mapping[fromager.packagesettings._typedefs.PackageVersion, list[str]])

  • config_settings (dict[str, str | list[str]])

  • download_source (fromager.packagesettings._models.DownloadSource)

  • env (dict[str, str])

  • git_options (fromager.packagesettings._models.GitOptions)

  • has_config (bool)

  • name (packaging.utils.NormalizedName)

  • project_override (fromager.packagesettings._models.ProjectOverride)

  • purl (fromager.packagesettings._models.PurlConfig | None)

  • resolver_dist (fromager.packagesettings._models.ResolverDist)

  • variants (collections.abc.Mapping[fromager.packagesettings._typedefs.Variant, fromager.packagesettings._models.VariantInfo])

field annotations: RawAnnotations | None = None

Arbitrary metadata for a package

field build_dir: BuildDirectory | None = None

sub-directory with setup.py or pyproject.toml

field build_options: BuildOptions [Optional]

Build system options

field changelog: VariantChangelog [Optional]

Changelog entries

field config_settings: dict[str, str | list[str]] [Optional]

PEP 517 arbitrary configuration for wheel builds

https://peps.python.org/pep-0517/#config-settings

config_settings:
  setup-args:
    - "-Dsystem-freetype=true"
    - "-Dsystem-qhull=true"

PEP 517 arbitrary configuration for wheel builds

https://peps.python.org/pep-0517/#config-settings

config_settings:
  setup-args:
    - "-Dsystem-freetype=true"
    - "-Dsystem-qhull=true"
field download_source: DownloadSource [Optional]

Alternative source download settings

Validated by:

  • before_none_dict

field env: EnvVars [Optional]

Common env var for all variants

field git_options: GitOptions [Optional]

Git repository cloning options

Validated by:

  • before_none_dict

field has_config: bool [Required]

package has override setting

field name: Package [Required]

Canonicalized package name

Constraints:

  • func = <function <lambda> at 0x707600d4b600>

  • json_schema_input_type = PydanticUndefined

field project_override: ProjectOverride [Optional]

Patch project settings

field purl: PurlConfig | None = None

Purl configuration for SBOM generation.

A PurlConfig object with individual field overrides and upstream source identification.

Changed in version 0.81.0: The purl option now requires a valid PURL config object instead of a string.

Purl configuration for SBOM generation.

A PurlConfig object with individual field overrides and upstream source identification.

Changed in version 0.81.0: The purl option now requires a valid PURL config object instead of a string.

field resolver_dist: ResolverDist [Optional]

Resolve distribution version

Validated by:

  • before_none_dict

field variants: Mapping[Variant, VariantInfo] [Optional]

Variant configuration

Validated by:

  • before_none_dict

serialize(self, mode: str = 'python', exclude_defaults: bool = True, exclude_unset: bool = True, exclude: set[str] | frozenset[str] = frozenset({'has_config', 'name'}), **kwargs: Any) → dict[str, Any]

Serialize package configuration

pydantic model fromager.packagesettings.BuildOptions

Build system options

build_ext_parallel: False  # DEPRECATED: ignored, will be removed
cpu_cores_per_job: 1
memory_per_job_gb: 1.0
Fields:

  • build_ext_parallel (bool)

  • cpu_cores_per_job (int)

  • exclusive_build (bool)

  • memory_per_job_gb (float)

field build_ext_parallel: bool = False

Configure build_ext[parallel] in DIST_EXTRA_CONFIG

Deprecated since version 0.72.0: This option is deprecated and will be removed in a future release. The parallel build feature for extensions is unsafe due to race conditions. This option is now ignored and will emit a warning if set to True.

Configure build_ext[parallel] in DIST_EXTRA_CONFIG

Deprecated since version 0.72.0: This option is deprecated and will be removed in a future release. The parallel build feature for extensions is unsafe due to race conditions. This option is now ignored and will emit a warning if set to True.

field cpu_cores_per_job: int = 1

Scale parallel jobs by available CPU cores

Examples:

1: as many parallel jobs as CPU logical cores

2: allocate 2 cores per job

Constraints:

  • ge = 1

field exclusive_build: bool = False

If true, this package must be built on its own (not in parallel with other packages). Default: False.

field memory_per_job_gb: float = 1.0

Scale parallel jobs by available virtual memory (without swap)

Examples:

0.5: assume each parallel job requires 512 MB virtual memory

Constraints:

  • ge = 0.1

pydantic model fromager.packagesettings.DownloadSource

Package download source

Download package sources from an alternative source, e.g. GitHub release.

url: https://example.com/package.tar.gz
destination_filename: ${dist_name}-${version}.tar.gz
Fields:

  • destination_filename (fromager.packagesettings._typedefs.Template | None)

  • url (fromager.packagesettings._typedefs.Template | None)

field destination_filename: Template | None = None

Rename file (filename without path)

Validated by:

  • validate_destination_filename

field url: Template | None = None

Source download url (string template)

pydantic model fromager.packagesettings.GitOptions

Git repository cloning options

submodules: False
submodule_paths: []
Fields:

  • submodule_paths (list[str])

  • submodules (bool)

field submodule_paths: list[str] [Optional]

Clone specific submodule paths only

If provided, only the specified submodule paths will be cloned. This option takes precedence over the ‘submodules’ boolean setting.

Examples: - [“third-party/openssl”] - [“vendor/lib1”, “vendor/lib2”]

Clone specific submodule paths only

If provided, only the specified submodule paths will be cloned. This option takes precedence over the ‘submodules’ boolean setting.

Examples: - [“third-party/openssl”] - [“vendor/lib1”, “vendor/lib2”]

field submodules: bool = False

Clone git submodules recursively?

When True, all submodules will be cloned recursively. When False (default), no submodules will be cloned.

Clone git submodules recursively?

When True, all submodules will be cloned recursively. When False (default), no submodules will be cloned.

pydantic model fromager.packagesettings.ResolverDist

Packages resolver dist

sdist_server_url: https://pypi.org/simple/
include_sdists: True
include_wheels: False
ignore_platform: False
Fields:

  • ignore_platform (bool)

  • include_sdists (bool)

  • include_wheels (bool)

  • min_release_age (int | None)

  • sdist_server_url (str | None)

  • use_pypi_org_metadata (bool | None)

field ignore_platform: bool = False

Ignore the platform when resolving with wheels? (default: no)

This option ignores the platform field (OS, CPU arch) when resolving with include_wheels enabled.

Added in version 0.52.

Ignore the platform when resolving with wheels? (default: no)

This option ignores the platform field (OS, CPU arch) when resolving with include_wheels enabled.

Added in version 0.52.

Validated by:

  • validate_ignore_platform

field include_sdists: bool = True

Use sdists to resolve? (default: yes)

Validated by:

  • validate_ignore_platform

field include_wheels: bool = False

Use wheels to resolve? (default: no)

Validated by:

  • validate_ignore_platform

field min_release_age: int | None = None

Per-package minimum release age override in days.

None (default): inherit the global --min-release-age setting. 0: disable the release-age cooldown for this package. Positive integer: override the cooldown with this many days.

Added in version 0.82.

Per-package minimum release age override in days.

None (default): inherit the global --min-release-age setting. 0: disable the release-age cooldown for this package. Positive integer: override the cooldown with this many days.

Added in version 0.82.

Constraints:

  • ge = 0

Validated by:

  • validate_ignore_platform

field sdist_server_url: str | None = None

Source distribution download server (default: PyPI)

Validated by:

  • validate_ignore_platform

field use_pypi_org_metadata: bool | None = None

Can use metadata from pypi.org JSON / Simple API?

None (default) is for auto-setting. Packages with customizations (config, patches, plugins) don’t use pypi.org metadata by default.

Added in version 0.70.

Can use metadata from pypi.org JSON / Simple API?

None (default) is for auto-setting. Packages with customizations (config, patches, plugins) don’t use pypi.org metadata by default.

Added in version 0.70.

Validated by:

  • validate_ignore_platform

pydantic model fromager.packagesettings.ProjectOverride

Override pyproject.toml settings

update_build_requires:
  - setuptools
remove_build_requires:
  - ninja
requires_external:
  - openssl-libs
Fields:

  • remove_build_requires (list[packaging.utils.NormalizedName])

  • requires_external (list[str])

  • update_build_requires (list[str])

field remove_build_requires: list[Package] [Optional]

Remove requirement from pyproject.toml [build-system] requires

Remove requirement from pyproject.toml [build-system] requires

field requires_external: list[str] [Optional]

Add / update Requires-External core metadata field

Each entry contains a string describing some dependency in the system that the distribution is to be used. See https://packaging.python.org/en/latest/specifications/core-metadata/#requires-external-multiple-use

Note

Fromager does not modify METADATA file, yet. Read the information from an importlib.metadata distribution with tomlkit.loads(dist(pkgname).read_text("fromager-build-settings")).

Add / update Requires-External core metadata field

Each entry contains a string describing some dependency in the system that the distribution is to be used. See https://packaging.python.org/en/latest/specifications/core-metadata/#requires-external-multiple-use

Note

Fromager does not modify METADATA file, yet. Read the information from an importlib.metadata distribution with tomlkit.loads(dist(pkgname).read_text("fromager-build-settings")).

field update_build_requires: list[str] [Optional]

Add / update requirements to pyproject.toml [build-system] requires

Add / update requirements to pyproject.toml [build-system] requires

Validated by:

  • validate_update_build_requires

pydantic model fromager.packagesettings.PurlConfig

Per-package purl configuration for SBOM generation.

Allows overriding individual purl components or specifying an upstream purl for packages sourced from GitHub/GitLab.

Added in version 0.81.0.

purl:
  type: generic
  name: custom-name
  repository_url: "https://example.com/simple"
  upstream: "pkg:github/org/repo@v1.0.0"
Fields:

  • name (str | None)

  • namespace (str | None)

  • repository_url (pydantic.networks.AnyUrl | None)

  • type (str | None)

  • upstream (str | None)

  • version (str | None)

field name: str | None = None

Override the purl name component (defaults to the package name)

field namespace: str | None = None

Override the purl namespace component

field repository_url: AnyUrl | None = None

Per-package override for the purl repository_url qualifier.

Overrides the global sbom.repository_url setting for this package.

field type: PurlType | None = None

Override the purl type (e.g. generic instead of pypi)

field upstream: UpstreamPurl | None = None

Full purl string identifying the upstream source package.

When set, this is used as the upstream identity in the SBOM’s GENERATED_FROM relationship. Used for packages sourced from GitHub/GitLab rather than PyPI.

When absent, the upstream purl is auto-derived from the downstream purl without the repository_url qualifier.

Full purl string identifying the upstream source package.

When set, this is used as the upstream identity in the SBOM’s GENERATED_FROM relationship. Used for packages sourced from GitHub/GitLab rather than PyPI.

When absent, the upstream purl is auto-derived from the downstream purl without the repository_url qualifier.

field version: str | None = None

Override the purl version component (defaults to the resolved version)

pydantic model fromager.packagesettings.SbomSettings

Global SBOM generation settings

sbom:
  supplier: "Organization: ExampleCo"
  namespace: "https://www.example.com"
  purl_type: pypi
  repository_url: "https://example.com/simple"
  creators:
    - "Organization: ExampleCo"
Fields:

  • creators (list[str])

  • namespace (pydantic.networks.AnyUrl)

  • purl_type (str)

  • repository_url (pydantic.networks.AnyUrl | None)

  • supplier (str)

field creators: list[str] [Optional]

Additional SPDX creator entries (e.g. Organization: ExampleCo)

The fromager tool creator entry is always added automatically.

field namespace: AnyUrl = AnyUrl('https://spdx.org/spdxdocs')

Base URL for the SPDX documentNamespace

field purl_type: PurlType = 'pypi'

Default purl type for all packages (e.g. pypi, generic)

Constraints:

  • strip_whitespace = True

  • to_lower = True

  • min_length = 1

field repository_url: AnyUrl | None = None

Default purl repository_url qualifier for all packages

When set, this URL is added to every purl as a qualifier (e.g. pkg:pypi/flask@2.0?repository_url=https://example.com/simple). Can be overridden per-package in the package settings file.

Default purl repository_url qualifier for all packages

When set, this URL is added to every purl as a qualifier (e.g. pkg:pypi/flask@2.0?repository_url=https://example.com/simple). Can be overridden per-package in the package settings file.

field supplier: str = 'NOASSERTION'

SPDX supplier field for the wheel package (e.g. Organization: ExampleCo)

Global Settings

The global changelogs can be placed in overrides/settings.yaml.

If you prefer managing a single settings file, per-package settings can also be kept in this file.

pydantic model fromager.packagesettings.SettingsFile

Models global settings file settings.yaml

changelog:
  cuda:
    - "2024-09-13: updated CUDA version"
  rocm:
    - "2024-09-01: updated ROCm version"
Fields:

  • changelog (collections.abc.Mapping[fromager.packagesettings._typedefs.Variant, list[str]])

  • sbom (fromager.packagesettings._models.SbomSettings | None)

field changelog: GlobalChangelog [Optional]

Changelog entries

field sbom: SbomSettings | None = None

SBOM generation settings

When set, Fromager generates SPDX 2.3 SBOM documents and embeds them in built wheels per PEP 770. When absent (default), no SBOMs are generated.

SBOM generation settings

When set, Fromager generates SPDX 2.3 SBOM documents and embeds them in built wheels per PEP 770. When absent (default), no SBOMs are generated.