Adding a New Package to the Fedora Distribution Repositories#

Overview#

Fedora is a community-driven Linux distribution built on the principle that free and open-source software should be accessible to everyone. One of the most impactful ways to contribute to Fedora is by packaging software — taking an upstream project and making it available to millions of Fedora users through the official distribution repositories.

The process of getting a new package into Fedora's repositories involves several distinct stages:

1. Account setup — Register a Fedora account and sign the contributor agreement
2. Environment setup — Install packaging tools and configure your development workspace
3. Package creation — Write a SPEC file, build RPMs locally, and validate them
4. Peer review — Submit a review request and work with a Fedora packager to verify compliance
5. Sponsorship — Receive sponsorship from an existing packager to gain commit access
6. Repository import — Import your package into dist-git and build it in Koji
7. Updates — Submit your package through Bodhi to reach end users

This guide walks you through each stage in detail. Whether you are packaging software for the first time or looking for a comprehensive reference, the Fedora packaging community is welcoming and support is available through mailing lists, IRC, and documentation. Don't hesitate to ask questions — every experienced Fedora packager was once a newcomer too.

Prerequisites#

Before you begin building your first package, you need to set up your accounts, development environment, and familiarize yourself with the guidelines that govern Fedora packaging.

1. Create a Fedora Account#

All Fedora contributors start by registering an account in the Fedora Account System (FAS):

1. Register at https://accounts.fedoraproject.org/
2. Sign the Fedora Project Contributor Agreement (FPCA) — this is a prerequisite for any contribution to Fedora

Your Fedora account is used across the entire ecosystem, including:

• Bugzilla (https://bugzilla.redhat.com/) — for filing and tracking package review requests and bug reports
• Koji (https://koji.fedoraproject.org/) — the official Fedora build system
• dist-git (https://src.fedoraproject.org/) — the git-based package source repository

2. Set Up Your Development Environment#

Install the essential RPM packaging tools on your Fedora system:

dnf install fedora-packager rpmdevtools rpmlint

Next, set up your RPM build workspace using the rpmdev-setuptree utility 1:

rpmdev-setuptree

This creates the standard ~/rpmbuild/ directory hierarchy 1:

Install fedora-review for automated review checks — this tool automates many of the checks that a package reviewer will perform:

dnf install fedora-review

Install mock for building packages in clean, isolated chroot environments 1:

dnf install mock

Note: You will need to add yourself to the mock group to use it without sudo:

⧉

sudo usermod -aG mock $USER

Log out and back in for the group change to take effect.

3. Understand the Packaging Guidelines#

Before creating your package, familiarize yourself with the Fedora Packaging Guidelines. These are the rules and conventions that all Fedora packages must follow, and your package will be checked against them during review.

Key areas of the guidelines include:

• Naming conventions — how to properly name your package and sub-packages
• Versioning — how to handle Version and Release fields
• Licensing — which licenses are acceptable and how to specify them
• File placement — where to install files (following the Filesystem Hierarchy Standard)
• Dependencies — how to correctly declare BuildRequires and Requires

Fedora also maintains language-specific packaging guidelines covering Python, Ruby, Perl, Java, Go, Rust, and many others. The RPM Packaging Guide notes that there are over 60 sets of application-specific guidelines, each with associated RPM macro sets 1. Always check whether a specific guideline exists for the language or framework of the software you are packaging.

The Package Creation Process#

With your environment set up, you are ready to create your RPM package. This section walks through the complete packaging workflow, from obtaining source code to a verified, tested package ready for review.

Step 1: Prepare the Source#

Obtain the upstream source code for the software you want to package. This is typically a compressed tarball (.tar.gz or .tar.xz) from the project's official release page.

Place the source archive in your SOURCES directory 1:

cp <package>-<version>.tar.gz ~/rpmbuild/SOURCES/

Alternatively, use spectool to download sources automatically once your SPEC file has a Source0 URL:

spectool -g ~/rpmbuild/SPECS/<package>.spec

Before proceeding, verify that the software uses a license that is acceptable for Fedora. Fedora only accepts open-source licenses that meet the Fedora licensing guidelines.

Step 2: Write the SPEC File#

The SPEC file is the "recipe" that tells rpmbuild how to build your package 1. Use rpmdev-newspec to generate a starter template:

cd ~/rpmbuild/SPECS
rpmdev-newspec <packagename>

This creates <packagename>.spec with placeholder fields that you fill in. The SPEC file has two main sections 1:

Preamble Directives#

1

Body Sections#

1

Using RPM Macros#

Use RPM macros wherever possible instead of hardcoded paths. This ensures your package works correctly across different Fedora versions and architectures 1:

%{_bindir} # /usr/bin
%{_libdir} # /usr/lib or /usr/lib64 (architecture-dependent)
%{_datadir} # /usr/share
%{_sysconfdir} # /etc
%{_docdir} # /usr/share/doc
%{name} # expands to the package Name
%{version} # expands to the package Version
%{buildroot} # the staging directory for installed files

You can evaluate any macro with rpm --eval %{macro_name} to see its current value.

Marking License and Documentation Files#

Always use %license and %doc tags in your %files section 1:

%files
%license LICENSE
%doc README.md CHANGES
%{_bindir}/%{name}

The %license tag ensures the license file is installed and properly labeled by RPM, even when users install with --nodocs. The %doc tag marks files as documentation that may be excluded with --nodocs.

Example Minimal SPEC File#

Name: mypkg
Version: 1.0
Release: 1%{?dist}
Summary: A brief description of mypkg

License: GPL-2.0-or-later
URL: https://example.com/%{name}
Source0: https://example.com/%{name}/releases/%{name}-%{version}.tar.gz

BuildRequires: gcc
BuildRequires: make

%description
A longer description of mypkg that spans one or more
paragraphs explaining what the software does.

%prep
%autosetup

%build
%configure
%make_build

%install
%make_install

%check
make test

%files
%license LICENSE
%doc README.md
%{_bindir}/%{name}

%changelog
* Tue May 19 2026 Your Name <your@email.com> - 1.0-1
- Initial package

Step 3: Build Locally#

Use rpmbuild to build your package. You can build just the source RPM (SRPM), just the binary RPM, or both at once 1:

# Build SRPM only
rpmbuild -bs ~/rpmbuild/SPECS/<package>.spec

# Build binary RPM only
rpmbuild -bb ~/rpmbuild/SPECS/<package>.spec

# Build both SRPM and binary RPM
rpmbuild -ba ~/rpmbuild/SPECS/<package>.spec

The resulting files are placed in ~/rpmbuild/SRPMS/ and ~/rpmbuild/RPMS/<arch>/ respectively.

Step 4: Verify with rpmlint#

Run rpmlint against your SPEC file, SRPM, and binary RPM to catch compliance issues 1:

rpmlint ~/rpmbuild/SPECS/<package>.spec
rpmlint ~/rpmbuild/SRPMS/<package>-*.src.rpm
rpmlint ~/rpmbuild/RPMS/<arch>/<package>-*.rpm

rpmlint reports errors and warnings. All errors must be addressed before submitting for review. Some warnings may be acceptable with proper justification, but each should be carefully evaluated.

For verbose explanations of each reported issue, add the -i flag:

rpmlint -i ~/rpmbuild/SPECS/<package>.spec

Step 5: Test Build with Mock#

Before submitting for review, build your package in a clean, isolated chroot environment using mock. This ensures your BuildRequires are complete and your package builds correctly in a pristine environment — not just on your local machine where dependencies may already be installed 1:

mock -r fedora-rawhide-x86_64 ~/rpmbuild/SRPMS/<package>-*.src.rpm

Mock will install the declared BuildRequires into a fresh chroot and attempt to build the package. If the build fails in mock but succeeds locally, you likely have undeclared build dependencies.

You can also build for specific Fedora releases:

# Build for Fedora 41
mock -r fedora-41-x86_64 ~/rpmbuild/SRPMS/<package>-*.src.rpm

Once your package builds cleanly in mock and passes rpmlint, it is ready for the review process.

Submitting for Review#

Every new package entering Fedora must go through a peer review process. An existing Fedora packager examines your SPEC file and built packages, verifies compliance with the Fedora Packaging Guidelines, and provides feedback. This quality gate helps maintain the high standards of the Fedora distribution.

Step 1: Host Your Files#

Before filing a review request, you need to make your SPEC file and SRPM accessible via public URLs. Common options include:

• A personal website or server
• A public Fedora People page (https://fedorapeople.org/~username/)
• A public object storage service or file host

The fedora-review tool and reviewers will need to download these files directly.

Step 2: File a Review Request in Bugzilla#

Create a new bug in Red Hat Bugzilla with the following settings:

• Product: Fedora
• Component: Package Review
• Summary: Review Request: <packagename> - <brief description>

In the bug description, include:

• A direct URL to your SPEC file
• A direct URL to your SRPM
• A description of the software being packaged
• Confirmation that you have verified the license is acceptable for Fedora
• The output of rpmlint on your SPEC, SRPM, and binary RPM
• The output of fedora-review -b <bug_number> (run this after filing the bug)

You can run fedora-review to auto-generate a review check report:

fedora-review -b <bugzilla_bug_number>

This tool performs many of the checks a reviewer will perform manually and generates a structured report. Including this output in your review request significantly speeds up the review process.

Step 3: Find a Reviewer#

Package reviews are conducted by existing Fedora packagers on a volunteer basis. There is no formal queue assignment — you need to find a reviewer who is willing to look at your package.

Ways to find a reviewer:

• Mailing list: Post to the devel@lists.fedoraproject.org mailing list announcing your review request
• IRC/Matrix: Ask in #fedora-devel on Libera.Chat or the equivalent Matrix channel
• Review swaps: Offer to review another contributor's package in exchange — this is a common and encouraged practice in the Fedora community

To find packages needing review that you could swap with, search Bugzilla for open "Package Review" bugs.

Step 4: Address Review Feedback#

Once a reviewer picks up your request, they will examine your package and leave comments in the Bugzilla ticket. Common review items include:

• Licensing: Is the License field accurate and in the correct SPDX format? Is the %license tag present?
• BuildRequires: Are all build-time dependencies declared explicitly?
• File ownership: Are all installed files and directories listed in %files?
• rpmlint output: Are all errors resolved and warnings justified?
• %check section: Does the package include tests if the upstream provides them?
• Macros: Are RPM macros used instead of hardcoded paths?
• Source URL: Does Source0 point to a canonical, accessible upstream URL?

For each issue raised, update your SPEC file, rebuild, and upload new versions of your SPEC and SRPM. Add a comment to the bug indicating what was changed. Repeat this process until the reviewer is satisfied and grants a positive review, indicated by a +1 comment and a status change on the bug.

Tip: Be responsive and treat feedback constructively. Reviewers are volunteers contributing their time, and the review process is a learning opportunity that makes your package better.

Getting Sponsored#

After your package receives a positive review, you need sponsorship before you can commit packages to the Fedora repositories. Sponsorship is a mechanism to ensure that new packagers have demonstrated the knowledge and skills necessary to maintain packages responsibly in the distribution.

Why Sponsorship is Required#

New Fedora contributors do not automatically gain commit access to the package repositories. A sponsor — an experienced Fedora packager — must vouch for you and add you to the packager group in the Fedora Account System (FAS). This serves as a quality gate and helps maintain the integrity of the distribution. More details on the policy can be found at the Fedora Packager Sponsor Policy.

How to Get Sponsored#

To get sponsored, you generally need to:

1. Complete a successful package review — A positive review (+1) on your Bugzilla review request demonstrates that you can write a correct, guideline-compliant package

2. Demonstrate understanding of the packaging guidelines — Reviewers and sponsors want to see that you understand why changes were requested, not just that you applied them

3. Engage with the community — Participate in the devel@lists.fedoraproject.org mailing list, ask questions in #fedora-devel, and offer to do review swaps. Being visible and helpful in the community makes sponsors more confident in sponsoring you

4. Ask for sponsorship — Once you have a positive review, ask the reviewer or another packager you have interacted with to sponsor you. Alternatively, post to the devel mailing list asking for a sponsor, with a link to your completed review request

What Happens During Sponsorship#

When a sponsor agrees to add you:

1. The sponsor adds your Fedora account to the packager group in FAS
2. You gain commit access to dist-git for your own packages and the ability to create new package repositories
3. You become a full Fedora package maintainer, with both the privileges and responsibilities that entails

Note: Sponsorship is not just a formality — your sponsor is partially vouching for your work. Maintain a good relationship with the community, respond to bug reports, and keep your packages updated.

After Approval — Getting Your Package into the Repositories#

Once you are sponsored and your review is complete, you can proceed to import your package into the Fedora infrastructure and submit it for distribution to users.

Step 1: Request a dist-git Repository#

Fedora uses dist-git (https://src.fedoraproject.org/) as its package source repository. Each package has its own git repository containing the SPEC file, patches, and references to source archives.

Request a new repository using the fedpkg command:

fedpkg request-repo <packagename>

Alternatively, you can file the request via the web interface at https://pagure.io/releng/fedora-scm-requests. In either case, you will need to provide the Bugzilla bug number of your approved package review.

The Release Engineering team will process your request. Once approved, your repository will be available at https://src.fedoraproject.org/rpms/<packagename>.

Step 2: Import Your Package#

Clone your new dist-git repository:

fedpkg clone <packagename>
cd <packagename>

Import your SRPM into the repository. This uploads the source archive to the Fedora lookaside cache and updates the SPEC file and related files in git:

fedpkg import ~/rpmbuild/SRPMS/<package>-*.src.rpm

Review the changes, then commit and push:

git add .
git commit -m "Initial import"
git push

Step 3: Build in Koji#

Fedora's official build system is Koji (https://koji.fedoraproject.org/). Submit your package build using fedpkg:

fedpkg build

This command submits a build task to Koji, which will compile your package for all supported Fedora architectures. You can monitor the build status at the Koji web interface or via the command line.

A successful build means your package is now built for all Fedora architectures and is ready for users to install from Bodhi updates.

Tip: If your build fails in Koji, examine the build logs carefully. Common failure reasons include missing BuildRequires, architecture-specific issues, or network access during build (not allowed in Koji's isolated build environment).

Step 4: Submit an Update via Bodhi#

After a successful Koji build, submit your package through Bodhi (https://bodhi.fedoraproject.org/), Fedora's updates management system:

fedpkg update

Or use the Bodhi web interface to create the update manually.

New packages typically enter as newpackage update type. Once submitted, the update enters a testing period in the updates-testing repository, where users can install and test it. Users provide feedback through a karma system — positive karma (+1) and negative karma (-1). After the update accumulates sufficient positive karma (typically +3) or after a mandatory testing period (usually 7 days), Bodhi automatically pushes the package to the stable repository where all Fedora users can install it.

Ongoing Maintenance#

Becoming a Fedora package maintainer means taking on the ongoing responsibility of keeping your package healthy and up to date. Fedora users depend on package maintainers to ensure software in the repositories is functional, secure, and current.

Keeping Your Package Updated#

When upstream releases a new version of the software you package:

1. Update the Version field in your SPEC file and reset Release to 1%{?dist}
2. Update Source0 if the URL changes
3. Run spectool -g to download the new source
4. Rebuild and test with rpmbuild -ba and mock
5. Add a %changelog entry describing the update
6. Import, build in Koji, and submit a Bodhi update

Consider using rpmautospec for automated changelog and release management — it can significantly simplify the maintenance workflow for frequent upstream releases.

Monitoring for Issues#

Stay on top of problems with your package:

• Bugzilla (https://bugzilla.redhat.com/) — Watch for new bugs filed against your package and respond promptly
• FTBFS (Fails To Build From Source) — Automated systems will notify you if your package fails to build during a Fedora mass rebuild (which occurs each release cycle). These must be fixed promptly or the package may be orphaned
• FTI (Fails To Install) — Notifications when your package cannot be installed due to dependency or other issues
• Release Engineering announcements — Subscribe to release-related mailing lists to stay informed about upcoming mass rebuilds, toolchain updates, and policy changes

Following Updated Guidelines#

The Fedora Packaging Guidelines evolve over time. Keep an eye on the packaging guidelines for changes that may affect your packages, and update your SPEC files accordingly.

Using fedpkg for Day-to-Day Work#

All interactions with dist-git and the Fedora build infrastructure should use fedpkg. Common commands include:

fedpkg clone <packagename> # Clone your package repository
fedpkg build # Submit a build to Koji
fedpkg update # Submit a Bodhi update
fedpkg switch-branch f41 # Switch to a Fedora release branch
fedpkg push # Push changes to dist-git
fedpkg lint # Run rpmlint on your SPEC file

Branching for Multiple Releases#

Fedora maintains separate branches for each active release (e.g., f41, f42, rawhide). You are responsible for maintaining your package on all active Fedora releases you choose to support. Use fedpkg switch-branch to work on specific release branches and keep them in sync with upstream fixes and updates.

If you are unable to maintain a package, you can orphan it in the package database, allowing another contributor to adopt it. Packages that remain orphaned for too long may be removed from the distribution.

Key Resources#

The following resources are essential references throughout the packaging process:

Tips for Success#

Packaging for Fedora is a skill that develops over time. Here are practical tips to help you succeed:

• Start with a simple package. A straightforward command-line tool written in C or a small Python utility with minimal dependencies is much easier to package than a complex application with many sub-packages. Build confidence with simple packages before tackling complex ones.

• Study existing SPEC files. Fedora's dist-git at https://src.fedoraproject.org/ contains thousands of actively maintained packages. Browse SPEC files for packages similar to yours (same language, similar type of software) to learn patterns and best practices from experienced maintainers.

• Use spectool to download sources. Rather than manually downloading upstream archives, add a proper Source0 URL to your SPEC file and use spectool -g <specfile> to fetch them automatically. This also makes it easier for reviewers to verify your sources.

• Run fedora-review before submitting. Use fedora-review -b <bug_number> (or fedora-review -n <packagename> -m /path/to/srpm for local testing) to automate the review checks. Addressing all issues flagged by fedora-review before submitting will significantly accelerate your review.

• Join the Fedora packaging community. Subscribe to the devel@lists.fedoraproject.org mailing list. It is the primary forum for packaging discussions, review swap requests, and announcements. The IRC/Matrix channel #fedora-devel on Libera.Chat is also an excellent place for real-time help.

• Offer review swaps. One of the best ways to find a reviewer for your package — and to learn packaging — is to review other people's packages. Look for open "Package Review" bugs in Bugzilla, pick one in a technology area you know, and offer to swap reviews.

• Use rpmautospec for automated release management. The rpmautospec tool can automatically compute the Release number and generate %changelog entries based on your git commit history. This reduces manual bookkeeping and makes maintaining packages easier over time.

• Be patient with the review process. Reviewers are volunteers. If your review sits without activity for a week or two, a polite bump on the mailing list or IRC is appropriate. Building relationships in the community is the most reliable way to get timely reviews.

• Keep your SPEC file clean and well-commented. A SPEC file that is easy to read and understand will be reviewed faster and is easier to maintain. Use comments to explain any non-obvious decisions, especially when suppressing rpmlint warnings.