DNF4.MODULARITY(7)

💖 dnf4.modularity — the manual, bestie edition 💖

okay so this is dnf4.modularity, and it's all about Modularity in DNF (that's the dnf4.modularity(7) manual, in case you were wondering which one you're reading). Welcome, pull up a chair, we're doing lore today. 🫶

⚠️ Warning: Modularity is deprecated, and functionality will be removed in a future release of DNF5. Like, it's still here, but it's on its way out. We're enjoying it while it lasts. 😭

Modularity is a new way of building, organizing and delivering packages. For more details see: <https://docs.pagure.org/modularity/> — go read it, it's giving ✨documentation✨.

---

✨ DEFINITIONS ✨

Gotta define the vocabulary first, because we're all gonna be using these words and I need you to be on the same page as me. No cap.

• modulemd — every repository can contain modules metadata with modulemd documents. These documents hold metadata about modules such as Name, Stream or list of packages. It's literally the info packet for a module. 📦
• (non-modular) package — a package that doesn't belong to a module. Just a regular lil guy living its life. 🙈
• modular package — a package that belongs to a module. It is listed in modulemd under the artifacts section. Modular packages can be also identified by having %{modularitylabel} RPM header set. The badge, the label, the identity. 💅
• (module) stream — a stream is a collection of packages, a virtual repository. It is identified with Name and Stream from modulemd separated with colon, for example "postgresql:9.6". Okay so here's the part you actually need to know: module streams can be active or inactive. active means the RPM packages from this stream are included in the set of available packages. Packages from inactive streams are filtered out. Streams are active either if marked as default or if they are explicitly enabled by a user action. Streams that satisfy dependencies of default or enabled streams are also considered active. And listen — only one stream of a particular module can be active at a given point in time. One. Singular. The main character stream. 👑

---

🎀 PACKAGE FILTERING 🎀

Without modules, packages with the highest version are used by default. Simple. Basic. Old school.

Module streams can distribute packages with lower versions than available in the repositories available to the operating system. To make such packages available for installs and upgrades, the non-modular packages are filtered out when their name or provide matches against a modular package name from any enabled, default, or dependent stream. Yes, that's a whole mouthful, it's giving complex, but it's the rules.

Also important, don't miss this: modular source packages will not cause non-modular binary packages to be filtered out. Noted. 📝

🧚 Demodularized rpms

Contains names of RPMs excluded from package filtering for particular module stream. When defined in the latest active module, non-modular RPMs with the same name or provide which were previously filtered out will reappear. Like wait, they're back?? Yes bestie, they reappear. Resurrection arc. 🌈

---

🔥 HOTFIX REPOSITORIES 🔥

In special cases, a user wants to cherry-pick individual packages provided outside module streams and make them available on along with packages from the active streams. Under normal circumstances, such packages are filtered out or rejected from getting on the system by Fail-safe mechanisms. Rude, honestly. 💀

So to make the system use packages from a repository regardless of their modularity, specify module_hotfixes=true in the .repo file. That's it. That protects the repository from package filtering. ✨

Please note the hotfix packages do not override module packages, they only become part of available package set. It's the package Epoch, Version and Release what determines if the the package is the latest. (Yes, "the the" is in the original, we're keeping the vibe exact, don't @ me. 😭)

---

🛡️ FAIL-SAFE MECHANISMS 🛡️

The safety nets. The seatbelts. The "we literally cannot let the wrong package through" energy.

💜 Repositories with module metadata are unavailable

When a repository with module metadata is unavailable, package filtering must keep working. Non-modular RPMs must remain unavailable and must never get on the system. Never ever. Periodt.

This happens when:

• user disables a repository via --disablerepo or uses --repoid
• user removes a .repo file from disk
• repository is not available and has skip_if_unavailable=true

DNF keeps copies of the latest modulemd for every active stream and uses them if there's no modulemd available for the stream. This keeps package filtering working correctly. Iconic behavior honestly, it's like a backup bestie who remembers everything for you. 🫶

The copies are made any time a transaction is resolved and started. That includes RPM transactions as well as any dnf module <enable|disable|reset> operations. Yeah. All of them. Covered. ✅

When the fail-safe data is used, dnf show such modules as part of @modulefailsafe repository. Remember that repo name, it's a whole clue. 🔍

🌸 Orphaned modular packages

All packages that are built as a part of a module have %{modularitylabel} RPM header set. If such package becomes part of RPM transaction and cannot be associated with any available modulemd, DNF prevents from getting it on the system — meaning the package is available, but cannot be installed, upgraded, etc. So close and yet so far. 😭

Good news though: packages from Hotfix repositories or Commandline repository are not affected by Fail-safe mechanisms. They're exempt. VIP pass. 💅

---

👑 Author

See AUTHORS in DNF source distribution.

💖 Copyright

2012-2020, Red Hat, Licensed under GPLv2+

---

and that's the whole page bestie, we ate and left no crumbs 🌟 this was DNF4.MODULARITY(7) from the DNF manual, version 4.24.0, dated Feb 19, 2026 — mwah, love you, go read the source too 🎀🦋