dnf

The dnf module offers pseudo-declarative package and repository management using dnf5.

Features

This module is capable of:

• Repository Management
  • Enabling/disabling COPR repos
  • Adding repo files via url or local files
  • Removing repos by specifying the repo name
  • Automatically cleaning up any repos added in the module
  • Adding keys for repos via url or local files
  • Adding non-free repos like rpmfusion and negativo17
• Package Management
  • Installing packages from RPM urls, local RPM files, or package repositories
  • Installing packages from a specific repository
  • Removing packages
  • Replacing installed packages with versions from another repository
• Optfix
  • Setup symlinks to /opt/ to allow certain packages to install

Repository Management

Add Repository Files

• Add repos from
  • any https:// or http:// URL
  • any .repo files located in ./files/dnf/ of your image repo
• If the OS version is included in the file name or URL, you can substitute it with the %OS_VERSION% magic string
  • The version is gathered from the VERSION_ID field of /usr/lib/os-release

type: dnf
repos:
  files:
    - https://brave-browser-rpm-release.s3.brave.com/brave-browser.repo
    - custom-file.repo # file path for /files/dnf/custom-file.repo

Add COPR Repositories

• COPR contains software repositories maintained by fellow Fedora users
• The chroot can be specified for the repo. The chroot is basically the OS in which the package was built.

type: dnf
repos:
  copr:
    - atim/starship
    - name: trixieua/mutter-patched
      chroot: fedora-42-x86_64

Disable/Enable Repositories

type: dnf
repos:
  files:
    add:
      - repo1
      - repo2
    remove:
      - repo3
  copr:
    enable:
      - ryanabx/cosmic-epoch
      - name: trixieua/mutter-patched
        chroot: fedora-42-x86_64
    disable:
      - kylegospo/oversteer

Add Repository Keys

type: dnf
repos:
  keys:
    - https://example.com/repo-1.asc
    - key2.asc

Add Non-free Repositories

This allows you to add a commonly used non-free repository. You can choose between negativo17 and rpmfusion. Your choice will also disable the opposite repository if it was already enabled.

type: dnf
repos:
  nonfree: negativo17

Options

There is currently only one option that can be specified in the repository management section.

• cleanup automatically cleans up repositories added in this section
  • Disabled by default

type: dnf
repos:
  cleanup: true

Package Management

Installing

Packages from Any Repository

type: dnf
install:
  packages:
    - package-1
    - package-2

Exclude packages

Optionally prevent packages from being installed. This is useful when a package pulls in another package as a dependency that you don’t want to install.

type: dnf
install:
  packages:
    - niri
  exclude:
    - alacritty
    - waybar
    - fuzzel

Packages from URL or File

• If the OS version is included in the file name or URL, you can substitute it with the %OS_VERSION% magic string
  • The version is gathered from the VERSION_ID field of /usr/lib/os-release

type: dnf
install:
  packages:
    - https://example.com/package-%OS_VERSION%.rpm
    - custom-file.rpm # install files/dnf/custom-file.rpm from the image repository

Packages from Specific Repositories

• Set repo to the name of the RPM repository, not the name or URL of the repo file

type: dnf
install:
  packages:
    - repo: copr:copr.fedorainfracloud.org:custom-user:custom-repo
      packages:
        - package-1

Package Groups

• See list of all package groups by running dnf5 group list --hidden on a live system
• Set the option with-optional to true to enable installation of optional packages in package groups

type: dnf
group-install:
  with-optional: true
  packages:
    - de-package-1
    - wm-package-2

Replace Packages

• You can specify one or more packages that will be swapped from another repo
• This process uses distro-sync to perform this operation
• All packages not specifying old: and new: will be swapped in a single transaction

type: dnf
replace:
  - from-repo: copr:copr.fedorainfracloud.org:custom-user:custom-repo
    packages:
      - package-1

• If a package has a different name in another repo, you can use the old: and new: properties
• This process uses swap to perform this operation for each set
• This process is ran before distro-sync

type: dnf
replace:
  - from-repo: repo-1
    packages:
      - old: old-package-2
        new: new-package-2

Options

The following options can specified in the package installation, group installation, and package replacement sections.

• install-weak-deps enables installation of the weak dependencies of RPMs
  • Enabled by default
  • Corresponds to the --setopt=install_weak_deps=True / --setopt=install_weak_deps=False flag
• skip-unavailable enables skipping packages unavailable in repositories without erroring out
  • Disabled by default
  • Corresponds to the --skip-unavailable flag
• skip-broken enables skipping broken packages without erroring out
  • Disabled by default
  • Corresponds to the --skip-broken flag
• allow-erasing allows removing packages in case of dependency problems during package installation
  • Disabled by default
  • Corresponds to the --allowerasing flag
• exclude allows excluding packages from being installed during package installation
  • Empty by default
  • Corresponds to the --exclude flag

type: dnf
install:
  skip-unavailable: true
  exclude:
    ...
  packages:
    ...
group-install:
  skip-broken: true
  exclude:
    ...
  packages:
    ...
replace:
  - from-repo: repo-1
    allow-erasing: true
    exclude:
      ...
    packages:
      ...

Removing

Packages

• You can set the auto-remove option to false to only remove the specific package and leave unused dependencies

type: dnf
remove:
  auto-remove: false
  packages:
    - package-1
    - package-2

Package Groups

type: dnf
group-remove:
  packages:
    - de-package-2

Optfix

• Optfix is a script used to work around problems with certain packages that install into /opt/
  • These issues are caused by Fedora Atomic storing /opt/ at the location /var/opt/ by default, while /var/ is only writeable on a live system
  • The script works around these issues by moving the folder to /usr/lib/opt/ and creating the proper symlinks at runtime
• Specify a list of folders inside /opt/

type: dnf
optfix:
  - brave.com
  - foldername

Note

This documentation page uses the installation of the Brave Browser as an example of a package that required a custom repository, with a custom key, and an optfix configuration to install properly. This is not an official endorsement of the Brave Browser by the BlueBuild project.

Example configuration

type: dnf
repos:
  cleanup: true # clean up added repos after module is done
  files:
    - https://brave-browser-rpm-release.s3.brave.com/brave-browser.repo
    - fury.repo
  copr:
    - atim/starship
    - trixieua/mutter-patched
  keys:
    - https://brave-browser-rpm-release.s3.brave.com/brave-core.asc
  nonfree: rpmfusion
optfix: # performs symlinking for `/opt/` to allow certain packages to install
  - Tabby # needed because tabby installs into `/opt/Tabby/`
  - brave.com
install:
  skip-unavailable: true # skip unavailable packages
  packages:
    - repo: brave-browser
      packages:
        - brave-browser
    - starship
    - https://github.com/Eugeny/tabby/releases/download/v1.0.209/tabby-1.0.209-linux-x64.rpm
    - kubectl.rpm
  exclude:
    - alacritty
remove:
  packages:
    - firefox
    - firefox-langpacks
replace:
  - from-repo: copr:copr.fedorainfracloud.org:trixieua:mutter-patched
    skip-unavailable: true # skip unavailable packages
    packages:
      - mutter
      - mutter-common
      - gdm
group-install:
  with-optional: true # install optional packages from group
  packages:
    - cosmic-desktop
    - cosmic-desktop-apps
    - window-managers
group-remove:
  packages:
    - development-tools

Configuration options

repos: (optional object)

No description provided…

cleanup: (optional boolean)

Cleans up the repos added in the same step after packages are installed.

Default: false

files: (optional enum)

List of paths or URLs to .repo files to import

Possible values: undefined, Unknown type

copr: (optional enum)

List of COPR project repos to add. You can also specify 2 lists instead to ‘enable’ or ‘disable’ COPR repos.

Possible values: Unknown type, Unknown type

keys: (optional array)

List of links to key files to import for installing from custom repositories.

nonfree: (optional enum)

Enable one of the nonfree repos.

This allows you to enable one of the nonfree repos. However, only one can be enabled at a time so if one is enabled, the other will be disabled if it is already enabled.

Possible values: negativo17, rpmfusion

optfix: (optional array)

DEPRECATED: List of folder names under /opt/ to enable for installing into.

group-remove: (optional object)

No description provided…

packages: (optional array)

List of RPM groups to remove.

group-install: (optional object)

No description provided…

packages: (optional array)

List of RPM groups to install.

with-optional: (optional boolean)

Include optional packages from group.

Default: false

install-weak-deps: (optional boolean)

Whether to install weak dependencies.

Default: true

skip-unavailable: (optional boolean)

Whether to continue with the install if there are no packages available in the repository.

Default: false

skip-broken: (optional boolean)

Whether to continue with the install if there are broken packages.

Default: false

allow-erasing: (optional boolean)

Whether to allow erasing (removal) of packages in case of dependency problems.

Default: false

exclude: (optional array)

A list of packages to prevent from being installed

remove: (optional object)

No description provided…

packages: (optional array)

List of RPM packages to remove.

auto-remove: (optional boolean)

Whether to remove unused dependencies during removal operation.

Default: true

install: (optional object)

No description provided…

packages: (optional array)

List of RPM packages to install.

Possible values: Unknown type, Unknown type

install-weak-deps: (optional boolean)

Whether to install weak dependencies.

Default: true

skip-unavailable: (optional boolean)

Whether to continue with the install if there are no packages available in the repository.

Default: false

skip-broken: (optional boolean)

Whether to continue with the install if there are broken packages.

Default: false

allow-erasing: (optional boolean)

Whether to allow erasing (removal) of packages in case of dependency problems.

Default: false

exclude: (optional array)

A list of packages to prevent from being installed

replace: (optional array)

List of configurations for replacing packages from another repo.