Command line reference

fromager

Usage

fromager [OPTIONS] COMMAND [ARGS]...

Options

--version: Show the version and exit.

-v, --verbose: report more detail to the console

--debug: report full tracebacks to the console

--log-file <log_file>: save detailed report of actions to file

--log-format <log_format>: python log format instructions, refer to https://docs.python.org/3/library/logging.html#logrecord-attributes for details

--error-log-file <error_log_file>: save error messages to a file

-O, --output-dir <output_dir>: base directory for sdists-repo, wheels-repo, and work-dir (default: current directory)

--build-wheel-server-url <build_wheel_server_url>: An optional URL for external web server for building wheels, to replace the built-in server. Must be configured to serve the path specified for –wheels-repo.

-p, --patches-dir <patches_dir>: location of files for patching source before building

--settings-file <settings_file>: location of the application settings file

--settings-dir <settings_dir>: location of per-package settings files

-c, --constraints-file <constraints_files>: location of the constraints files. Constraints are merged and checked for conflicts. Supports local path and remote from https://

--cleanup, --no-cleanup: control removal of working files when a build completes successfully

--variant <variant>: the build variant name

-j, --jobs <jobs>: maximum number of jobs to run in parallel

--network-isolation, --no-network-isolation

Build sdist and when with network isolation (unshare -cn)

Default:: False

--min-release-age <min_release_age>: Reject package versions published fewer than this many days ago (0 disables the check).

bootstrap

Compute and build the dependencies of a set of requirements recursively

TOPLEVEL is a requirements specification, including a package name and optional version constraints.

Usage

fromager bootstrap [OPTIONS] [TOPLEVEL]...

Options

-r, --requirements-file <requirements_files>: pip requirements file

-p, --previous-bootstrap-file <previous_bootstrap_file>: graph file produced from a previous bootstrap

-c, --cache-wheel-server-url <cache_wheel_server_url>: url to a wheel server from where fromager can download the wheels that it has built before

--sdist-only, --full-build: –sdist-only (fast mode) does not build missing wheels unless they are build requirements. –full-build (default) builds all missing wheels.

--skip-constraints: Skip generating constraints.txt file to allow building collections with conflicting versions

--test-mode: Test mode: continue processing after failures, report failures at end

--multiple-versions: Bootstrap all matching versions instead of only the highest version

--max-release-age <max_release_age>: Reject package versions published more than this many days ago.

Arguments

TOPLEVEL: Optional argument(s)

bootstrap-parallel

Bootstrap and build-parallel

Bootstraps all dependencies in sdist-only mode, then builds the remaining wheels in parallel. The bootstrap step downloads sdists and builds build-time dependency in serial. The build-parallel step builds the remaining wheels in parallel.

Note: –test-mode is not supported in parallel builds. Use the serial bootstrap command for test mode.

Usage

fromager bootstrap-parallel [OPTIONS] [TOPLEVEL]...

Options

-r, --requirements-file <requirements_files>: pip requirements file

-p, --previous-bootstrap-file <previous_bootstrap_file>: graph file produced from a previous bootstrap

-c, --cache-wheel-server-url <cache_wheel_server_url>: url to a wheel server from where fromager can download the wheels that it has built before

--skip-constraints: Skip generating constraints.txt file to allow building collections with conflicting versions

-f, --force: rebuild wheels even if they have already been built

-m, --max-workers <max_workers>: maximum number of parallel workers to run (default: unlimited)

--multiple-versions: Bootstrap all matching versions instead of only the highest version

--max-release-age <max_release_age>: Reject package versions published more than this many days ago.

Arguments

TOPLEVEL: Optional argument(s)

build

Build a single version of a single wheel

DIST_NAME is the name of a distribution

DIST_VERSION is the version to process

SDIST_SERVER_URL is the URL for a PyPI-compatible package index hosting sdists

Downloads the source distribution.
Unpacks it and prepares the source via patching, vendoring rust dependencies, etc.
Prepares a build environment with the build dependencies.
Builds the wheel.

Refer to the ‘step’ commands for scripting these stages separately.

Usage

fromager build [OPTIONS] DIST_NAME DIST_VERSION SDIST_SERVER_URL

Options

--wheel-server-url <wheel_server_url>: URL for the wheel server for builds

Arguments

DIST_NAME: Required argument

DIST_VERSION: Required argument

SDIST_SERVER_URL: Required argument

build-order

Commands for working with build-order files

Usage

fromager build-order [OPTIONS] COMMAND [ARGS]...

as-csv

Create a comma-separated-value file from the build order file

BUILD_ORDER_FILE is one or more build-order.json files to convert

Creates a file suitable for import into a spreadsheet including the distribution name, version, original requirement, dependency type, whether the package is pre-built, the build order step number, and a full dependency chain leading to the requirement.

Usage

fromager build-order as-csv [OPTIONS] BUILD_ORDER_FILE

Options

-o, --output <output>: output file to create

Arguments

BUILD_ORDER_FILE: Required argument

summary

Summarize the build order files

BUILD_ORDER_FILE is one or more build-order.json files to convert

Creates a comma-separated-value file including the distribution name, the build order file that included it, which versions are used in each, and where they match.

Usage

fromager build-order summary [OPTIONS] [BUILD_ORDER_FILE]...

Options

-o, --output <output>: output file to create

Arguments

BUILD_ORDER_FILE: Optional argument(s)

build-parallel

Build wheels in parallel based on a dependency graph

GRAPH_FILE is a graph.json file containing the dependency relationships between packages

Performs parallel builds of wheels based on their dependency relationships. Packages that have no dependencies or whose dependencies are already built can be built concurrently. By default, all possible packages are built in parallel. Use –max-workers to limit the number of concurrent builds.

Usage

fromager build-parallel [OPTIONS] GRAPH_FILE

Options

-f, --force: rebuild wheels even if they have already been built

-c, --cache-wheel-server-url <cache_wheel_server_url>: url to a wheel server from where fromager can check if it had already built the wheel

-m, --max-workers <max_workers>: maximum number of parallel workers to run (default: unlimited)

Arguments

GRAPH_FILE: Required argument

build-sequence

Build a sequence of wheels in order

BUILD_ORDER_FILE is the build-order.json files to build

SDIST_SERVER_URL is the URL for a PyPI-compatible package index hosting sdists

Performs the equivalent of the ‘build’ command for each item in the build order file.

Usage

fromager build-sequence [OPTIONS] BUILD_ORDER_FILE

Options

-f, --force: rebuild wheels even if they have already been built

-c, --cache-wheel-server-url <cache_wheel_server_url>: url to a wheel server from where fromager can check if it had already built the wheel

Arguments

BUILD_ORDER_FILE: Required argument

canonicalize

convert a package name to its canonical form for use in override paths

Usage

fromager canonicalize [OPTIONS] [DIST_NAME]...

Arguments

DIST_NAME: Optional argument(s)

download-sequence

Download a sequence of source distributions in order.

BUILD_ORDER_FILE is the build-order.json files to build

SDIST_SERVER_URL is the URL for a PyPI-compatible package index hosting sdists

Performs the equivalent of the ‘step download-source-archive’ command only for items in the build order file that have source_url_type as sdist.

Usage

fromager download-sequence [OPTIONS] BUILD_ORDER_FILE SDIST_SERVER_URL

Options

-w, --include-wheels

--ignore-missing-sdists

--num-threads <num_threads>

Arguments

BUILD_ORDER_FILE: Required argument

SDIST_SERVER_URL: Required argument

find-updates

Find available updates for packages with specific version constraints.

This command reads a constraints file and for each package that has a supported constraint (==, <, <=, ~=, !=, ===), it lists newer versions available. Constraints with lower bounds (>=) are ignored as they don’t pin to specific versions.

The CONSTRAINTS_FILE should be a pip-style constraints file with entries like: - “package_name==1.0.0” (will look for versions > 1.0.0) - “package_name<2.0.0” (will look for versions >= 2.0.0) - “package_name<=1.5.0” (will look for versions > 1.5.0) - “package_name~=1.4.0” (will look for versions outside compatible range) - “package_name!=1.0.0” (will look for versions other than 1.0.0) - “package_name===1.0.0” (will look for versions other than exactly 1.0.0) - “package_name>=1.0.0” (ignored - not a specific constraint)

Distribution types: - “default”: Use package settings for include_sdists/include_wheels - “sdist”: Only include source distributions - “wheel”: Only include wheels - “both”: Include both source distributions and wheels

Output formats: - “requirements”: List as requirement specifiers (package==version) - “json”: JSON array of objects with “name” and “version” fields - “csv”: CSV format with “name” and “version” columns

Use –output to write results to a file instead of stdout.

Usage

fromager find-updates [OPTIONS] CONSTRAINTS_FILE

Options

--format <output_format>

Output format (requirements: name==version, json: JSON array, csv: CSV with name,version columns)

Options:: OutputFormat.REQUIREMENTS | OutputFormat.JSON | OutputFormat.CSV

--distribution-type <distribution_type>

Distribution type to include in version lookup (default: use package settings, sdist: source only, wheel: wheels only, both: include both sdists and wheels)

Options:: DistributionType.DEFAULT | DistributionType.SDIST | DistributionType.WHEEL | DistributionType.BOTH

--sdist-server-url <sdist_server_url>: URL to the Python package index to use for version lookup

-o, --output <output>: Write output to file instead of stdout

Arguments

CONSTRAINTS_FILE: Required argument

graph

Commands for working with graph files

Usage

fromager graph [OPTIONS] COMMAND [ARGS]...

build-graph

Print build graph steps for parallel-build

The build-graph command takes a graph.json file and analyzes in which order parallel build is going to build the wheels. It also shows which wheels are recognized as build dependencies or exclusive builds.

Usage

fromager graph build-graph [OPTIONS] GRAPH_FILE

Arguments

GRAPH_FILE: Required argument

explain-duplicates

Report on duplicate installation requirements, and where they come from.

Usage

fromager graph explain-duplicates [OPTIONS] GRAPH_FILE

Arguments

GRAPH_FILE: Required argument

find-best-fit

Find the best-fit collection for each onboarding package.

Analyzes dependency overlap between top-level packages in ONBOARDING_GRAPH and the existing COLLECTION_GRAPHS to recommend where each onboarding package should be placed.

For each top-level package in the onboarding graph, computes the full transitive dependency closure and compares it against every collection. Collections are ranked by fewest new packages required, then by highest dependency coverage.

ONBOARDING_GRAPH Path to the onboarding collection graph.json.

COLLECTION_GRAPHS One or more paths to existing collection graph.json files.

Usage

fromager graph find-best-fit [OPTIONS] ONBOARDING_GRAPH COLLECTION_GRAPHS...

Options

--format <output_format>

Output format (default: table)

Options:: table | json

Arguments

ONBOARDING_GRAPH: Required argument

COLLECTION_GRAPHS: Required argument(s)

migrate-graph

Convert a old graph file into the the new format

Usage

fromager graph migrate-graph [OPTIONS] GRAPH_FILE

Options

-o, --output <output>

Arguments

GRAPH_FILE: Required argument

subset

Extract a subset of a build graph related to a specific package.

Creates a new graph containing only nodes that depend on the specified package and the dependencies of that package. By default includes all versions of the package, but can be limited to a specific version with –version.

Usage

fromager graph subset [OPTIONS] GRAPH_FILE PACKAGE_NAME

Options

-o, --output <output>: Output file path for the subset graph

--version <version>: Limit subset to specific version of the package

Arguments

GRAPH_FILE: Required argument

PACKAGE_NAME: Required argument

to-constraints

Convert a graph file to a constraints file.

Usage

fromager graph to-constraints [OPTIONS] GRAPH_FILE

Options

-o, --output <output>

Arguments

GRAPH_FILE: Required argument

to-dot

Convert a graph file to a DOT file suitable to pass to graphviz.

Usage

fromager graph to-dot [OPTIONS] GRAPH_FILE

Options

-o, --output <output>

--install-only: Only show installation dependencies, excluding build dependencies

--overrides-only: Only include nodes with fromager overrides (settings, patches, or plugins)

Arguments

GRAPH_FILE: Required argument

why

Explain why a dependency shows up in the graph

Usage

fromager graph why [OPTIONS] GRAPH_FILE PACKAGE_NAME

Options

--version <version>: filter by version for the given package

--depth <depth>: recursively get why each package depends on each other. Set depth to -1 for full recursion till root

--requirement-type <requirement_type>: filter by requirement type

Arguments

GRAPH_FILE: Required argument

PACKAGE_NAME: Required argument

lint

Review existing settings and overrides for potential configuration errors.

Usage

fromager lint [OPTIONS]

lint-requirements

Command to lint the constraints.txt and requirements.txt files This command takes a single wildcard path string for constraints.txt and requirements.txt. It checks the formatting of these files and reports issues if found. Files with names that end with constraints.txt (e.g. constraints.txt, global-constraints.txt, etc.) are not allowed to contain extra dependencies. Additionally, it resolves valid input requirements to ensure we can find a matching version of each package.

Usage

fromager lint-requirements [OPTIONS] INPUT_FILES_PATH...

Options

--resolve-requirements, --no-resolve-requirements

Resolve requirement and fail if a package or version cannot be resolved

Default:: False

Arguments

INPUT_FILES_PATH: Required argument(s)

list-overrides

List all of the packages with overrides in the current configuration.

Usage

fromager list-overrides [OPTIONS]

Options

--details: Show more details about the overrides.

--format <output_format>

Output format for detailed view (requires –details, default: table)

Options:: table | csv | json

-o, --output <output>: Output file to create (requires –details, default: stdout)

list-versions

List all available versions for a package requirement specifier.

Usage

fromager list-versions [OPTIONS] REQUIREMENT_SPEC

Options

--distribution-type <distribution_type>

Distribution type to include in version lookup (default: use package settings, sdist: source only, wheel: wheels only, both: include both sdists and wheels)

Options:: DistributionType.DEFAULT | DistributionType.SDIST | DistributionType.WHEEL | DistributionType.BOTH

--sdist-server-url <sdist_server_url>: URL to the Python package index to use for version lookup

--ignore-no-versions, --no-ignore-no-versions: Do not treat missing versions as an error

--format-as-requirements, --no-format-as-requirements: Format output as requirement specifiers (name==version) instead of just version numbers

Arguments

REQUIREMENT_SPEC: Required argument

migrate-config

Migrate Fromager 0.27 config to new format

Usage

fromager migrate-config [OPTIONS]

Options

--envs-dir <envs_dir>: Required location of old environment override files

--settings-file <settings_file>: Required location of the old application settings file

--output-dir <output_dir>: Required location to write per-package settings

minimize

Minimize a requirements.txt file by removing packages that would be automatically included as dependencies of other packages.

Takes a requirements.txt file and a graph file as input and produces a minimized requirements.txt file that removes redundant dependencies. This helps avoid conflicts and reduces the overall graph size.

Usage

fromager minimize [OPTIONS] REQUIREMENTS_FILENAME GRAPH_FILENAME

Options

-o, --output <output>: Output file for minimized requirements (default: stdout)

Arguments

REQUIREMENTS_FILENAME: Required argument

GRAPH_FILENAME: Required argument

package

Commands for resolving package versions

Usage

fromager package [OPTIONS] COMMAND [ARGS]...

list-versions

List all available versions for a package requirement specifier.

The REQUIREMENT_SPEC should be a package requirement specification like: - “package_name” (any version) - “package_name>=1.0” (versions >= 1.0) - “package_name==1.*” (versions matching 1.*)

This command uses the get_resolver_provider hook to retrieve a resolver provider for the package in case there is a custom provider configured.

Distribution types: - “default”: Use package settings for include_sdists/include_wheels - “sdist”: Only include source distributions - “wheel”: Only include wheels - “both”: Include both source distributions and wheels

Output formats: - “versions”: one version per line (default) - “requirements”: name==version per line (pip-installable pins) - “table”: Rich table with upload timestamps, age, and cooldown status - “csv”: CSV with the same detail columns - “json”: JSON array with the same detail columns

Use –ignore-per-package-overrides to see what the global cooldown policy would block without per-package exemptions.

Usage

fromager package list-versions [OPTIONS] REQUIREMENT_SPEC

Options

--distribution-type <distribution_type>

Distribution type to include in version lookup (default: use package settings, sdist: source only, wheel: wheels only, both: include both sdists and wheels)

Options:: DistributionType.DEFAULT | DistributionType.SDIST | DistributionType.WHEEL | DistributionType.BOTH

--sdist-server-url <sdist_server_url>: URL to the Python package index to use for version lookup

--ignore-no-versions, --no-ignore-no-versions: Do not treat missing versions as an error

--format <output_format>

Output format (default: versions)

Options:: versions | requirements | table | csv | json

-o, --output <output>: Output file (default: stdout)

--ignore-per-package-overrides: Ignore per-package min_release_age overrides when computing cooldown status; uses only the global –min-release-age value.

Arguments

REQUIREMENT_SPEC: Required argument

resolve

Resolve a package with Fromager’s resolver and PyPI

The package resolver subcommand is a debug tool. It shows information about the package’s resolver configuration and resolves a package in two way. First, it resolves with Fromager’s resolver. Second, it performs a simple query against PyPI and compares the results.

Usage:

$ fromager --variant cpu package resolve 'fromager>=0.70'

Usage

fromager package resolve [OPTIONS] REQUIREMENT_SPEC

Options

--distribution-type <distribution_type>

Distribution type to include in version lookup (default: use package settings, sdist: source only, wheel: wheels only, both: include both sdists and wheels)

Options:: DistributionType.DEFAULT | DistributionType.SDIST | DistributionType.WHEEL | DistributionType.BOTH

--sdist-server-url <sdist_server_url>: URL to the Python package index to use for version lookup

Arguments

REQUIREMENT_SPEC: Required argument

stats

Show statistics about packages in a build

REQ_FILE is the requirements.txt file used for the build

GRAPH_FILE is the fromager graph.json file produced by the build

Shows a table with various statistics about the packages including counts of unique packages, constraints, configurations, prebuilt packages, patches, and build plugins.

Usage

fromager stats [OPTIONS] REQ_FILE GRAPH_FILE

Arguments

REQ_FILE: Required argument

GRAPH_FILE: Required argument

step

Step-by-step commands

Usage

fromager step [OPTIONS] COMMAND [ARGS]...

build-sdist

build a new source distribution for the package

DIST_NAME is the name of a distribution

DIST_VERSION is the version to process

The source distribution is placed in the sdists-repo/builds directory.

Usage

fromager step build-sdist [OPTIONS] DIST_NAME DIST_VERSION

Arguments

DIST_NAME: Required argument

DIST_VERSION: Required argument

build-wheel

build a wheel from prepared source

DIST_NAME is the name of a distribution

DIST_VERSION is the version to process

Usage

fromager step build-wheel [OPTIONS] DIST_NAME DIST_VERSION

Options

--wheel-server-url <wheel_server_url>: URL for the wheel server for builds

Arguments

DIST_NAME: Required argument

DIST_VERSION: Required argument

download-source-archive

download the source code archive for one version of one package

DIST_NAME is the name of a distribution

DIST_VERSION is the version to process

SDIST_SERVER_URL is the URL for a PyPI-compatible package index hosting sdists

Usage

fromager step download-source-archive [OPTIONS] DIST_NAME DIST_VERSION
                                      SDIST_SERVER_URL

Arguments

DIST_NAME: Required argument

DIST_VERSION: Required argument

SDIST_SERVER_URL: Required argument

prepare-build

set up build environment to build the package

DIST_NAME is the name of a distribution

DIST_VERSION is the version to process

Usage

fromager step prepare-build [OPTIONS] DIST_NAME DIST_VERSION

Options

--wheel-server-url <wheel_server_url>: URL for the wheel server for builds

Arguments

DIST_NAME: Required argument

DIST_VERSION: Required argument

prepare-source

ensure the source code is in a form ready for building a wheel

DIST_NAME is the name of a distribution

DIST_VERSION is the version to process

Usage

fromager step prepare-source [OPTIONS] DIST_NAME DIST_VERSION

Arguments

DIST_NAME: Required argument

DIST_VERSION: Required argument

wheel-server

Start a web server to serve the local wheels-repo

Usage

fromager wheel-server [OPTIONS]

Options

-p, --port <port>: the port to listen on

-i, --ip, --address <address>: the address to listen on, defaults to localhost