quickstart.rst

Quick Start

This guide gets you from zero to your first wheel build in under 5 minutes.

Prerequisites

You'll need Python 3.12 or later and network access to download packages from PyPI.

Installation

Install fromager using pip:

$ pip install fromager
$ fromager --version
fromager, version X.Y.Z

Your First Build

Let's build a simple package and its dependencies from source. We'll use stevedore, a lightweight package with minimal dependencies.

Create a requirements.txt file with the package name:

$ echo "stevedore" > requirements.txt

Run the bootstrap command:

$ fromager bootstrap -r requirements.txt

primary settings file: overrides/settings.yaml
per-package settings dir: overrides/settings
variant: cpu
...
100%|████████████████████████████████████████| 3/3 [00:08<00:00,  2.67s/pkg]
writing installation dependencies to ./work-dir/constraints.txt

Check your results:

$ ls wheels-repo/downloads/
pbr-6.1.0-0-py2.py3-none-any.whl
setuptools-75.1.0-0-py3-none-any.whl
stevedore-5.3.0-0-py3-none-any.whl

You've built stevedore and its dependencies (pbr, setuptools) entirely from source. Fromager downloaded the source distributions from PyPI, figured out the build and runtime dependencies, built each package in the correct order, and created wheels in wheels-repo/downloads/.

For a detailed explanation of the output files and directories, see :doc:`reference/files`.

Pinning Versions with Constraints

For reproducible builds, use a constraints file to pin specific versions:

$ echo "stevedore==5.3.0" > constraints.txt
$ fromager -c constraints.txt bootstrap -r requirements.txt

The -c option ensures fromager uses exactly the versions you specify.

Next Steps

Now that you've seen fromager work with a simple package, explore:

Learn More:

• :doc:`getting-started` - Detailed walkthrough with debugging examples
• :doc:`concepts/index` - Understand how fromager works

Common Tasks:

• :doc:`how-tos/containers` - Run fromager in containers (recommended)
• :doc:`how-tos/bootstrap-constraints` - Pin versions for reproducible builds
• :doc:`how-tos/repeatable-builds` - Ensure consistent builds across environments

Customize Builds:

• :doc:`customization` - Comprehensive customization guide
• :doc:`reference/config-reference` - Configuration reference
• :doc:`how-tos/index` - Task-oriented guides