DNF5.CONF(5)

📦
version 5.4.6.0 · 10 versions
, in fedora 44

💖 NAME 💖

okay so bestie, this is dnf5.conf(5) from the dnf5 manual — aka the DNF5 Configuration Reference. 💅✨

🌸 DESCRIPTION 🌸

DNF5 by default uses the global configuration file at /etc/dnf/dnf.conf. 🫶

The configuration file has INI format consisting of section declaration and name=value options below each on separate line. There are two types of sections in the configuration files: main and repository. The main section defines all global configuration options and should be only one. 👑

The repository sections define the configuration for each (remote or local) repository. The section name of the repository in brackets serve as repo ID reference and should be unique across configuration files. The allowed characters of repo ID string are lower and upper case alphabetic letters, digits, -, _, . and :. The minimal repository configuration file should aside from repo ID consists of baseurl, metalink or mirrorlist option definition. 🌈

✨ [MAIN] OPTIONS ✨

allow_downgrade — boolean

If enabled, DNF5 allows downgrading packages while resolving dependencies. 😌

  • Default: True.

allow_vendor_change — boolean

If disabled, DNF5 will stick to the original vendor during RPM upgrades or downgrades. This preference, however, can be fine-tuned using Vendor change policies <# dnf5-vendor-change-policy-label>. 🧚

  • Default: True.
Warning: This option is currently not supported for downgrade and distro-sync commands. 💀

assumeno — boolean

If enabled DNF5 will assume No where it would normally prompt for confirmation from user input. 🙅‍♀️

  • Default: False.

assumeyes — boolean

If enabled DNF5 will assume Yes where it would normally prompt for confirmation from user input (see also defaultyes). ✅

  • Default: False.

best — boolean

If True, instructs the solver to either use a package with the highest available version or fail. If False, do not fail if the latest version cannot be installed and go with the lower version. 👑

  • Default: True.
Note: This option in particular can be overridden by a distribution-specific configuration. For more details see drop-in configuration directories. 📁

cachedir — string

Path to a directory used by various DNF5 subsystems for storing cache data including repositories metadata and downloaded packages. Has a reasonable root-writable default depending on the distribution. DNF5 needs to be able to create files and directories at this location. 🗂️

  • Regular user default: ~/.cache/libdnf5.
  • For superuser the value is overwritten by system_cachedir option.

cacheonly — string

Can be all, metadata, none. 🌟

If set to all DNF5 will run entirely from system cache, will not update the cache and will use the system cache even if it is expired.

If set to metadata DNF5 will cache metadata only.

  • Default: none.
Note: API Notes: Must be set before repository objects are created. Plugins must set this in the pre_config hook. Later changes are ignored. ⚠️

check_config_file_age — boolean

If enabled DNF5 should automatically expire metadata of repos, which are older than their corresponding configuration file (usually the dnf.conf file and the foo.repo file). ⏳

  • Default: True.
Note: Expire of metadata is also affected by metadata age. See also metadata_expire. 🕰️

clean_requirements_on_remove — boolean

If enabled, DNF5 will remove dependencies that are no longer used during dnf remove. A package only qualifies for removal via clean_requirements_on_remove if it was installed through DNF5 but not on explicit user request, i.e. it was pulled in as a dependency. 🧹

installonlypkgs are never automatically removed.

  • Default: True.

debugdir — string

Location where libsolv debug files will be created when enabled by debug_solver. 🐛

  • Default: ./debugdata.

debug_solver — boolean

If enabled, libsolv debug files will be created when solving the transaction. The debug files are created in the debugdir directory. 🔍

  • Default: False.

defaultyes — boolean

If enabled, the default answer to user confirmation prompts will be Yes. Not to be confused with assumeyes which will not prompt at all. 💖

  • Default: False.

destdir — string

Redirect downloaded packages to provided directory. 📦

  • Default: <package repository cachedir>/packages

exclude_from_weak — list

Prevent installing packages as weak dependencies (recommends or supplements). The packages can be specified by a name or a glob and separated by a comma. 🚫

  • Defaults to [].

exclude_from_weak_autodetect — boolean

If enabled, DNF5 will autodetect unmet weak dependencies (recommends or supplements) of packages installed on the system. Providers of these weak dependencies will not be installed by dnf as weak dependencies any more (they will still be installed if pulled in as a regular dependency). 🤖

  • Defaults to true.

excludeenvs — list

Exclude environments, specified by an id or a glob and separated by a comma, from all operations. 🌍

Can be disabled using disable_excludes config option.

  • Default: [].

excludegroups — list

Exclude groups, specified by an id or a glob and separated by a comma, from all operations. 👥

Can be disabled using disable_excludes config option.

  • Default: [].

gpgcheck

Due to compatibility gpgcheck option is supported as well but pkg_gpgcheck is preferred. The meaning of gpgcheck is controlled by the gpgcheck_policy option. 🔐

  • Default: pkg_gpgcheck value.

gpgcheck_policy — legacy, full, or all

Controls how the gpgcheck option expands when explicitly set in a configuration section. 🕵️‍♀️

  • legacy — gpgcheck=1 sets only pkg_gpgcheck=1. This preserves the original DNF behavior.
  • full — gpgcheck=1 sets both pkg_gpgcheck=1 and repo_gpgcheck=1.
  • all — gpgcheck=1 sets pkg_gpgcheck=1, repo_gpgcheck=1, and localpkg_gpgcheck=1.

Explicitly setting pkg_gpgcheck, repo_gpgcheck, or localpkg_gpgcheck in the same configuration section overrides the policy for that specific option.

The policy is a global setting defined in [main] and affects all repository sections that use gpgcheck.

  • Default: legacy.

group_package_types — list

List of the following: optional, default, mandatory or conditional. 🎀

Tells DNF5 which type of packages in groups will be installed when group install <group-spec> or install @<group-spec> is called.

  • Default: default, mandatory, conditional.

ignorearch — boolean

If enabled, RPM will allow attempts to install packages incompatible with the CPU's architecture. 💻

  • Default: False.

installonlypkgs — list

List of provide names of packages that should only ever be installed, never upgraded. Kernels in particular fall into this category. These packages are never removed by dnf autoremove even if they were installed as dependencies (see clean_requirements_on_remove for auto removal details). This option append the list values to the default installonlypkgs list used by DNF5. The number of kept package versions is regulated by installonly_limit. 🧠

installonly_limit — integer

Number of installonly packages allowed to be installed concurrently. 🔢

1 is explicitly not allowed since it complicates kernel upgrades due to protection of the running kernel from removal.

Minimum is 2.

0 means unlimited number of installonly packages.

  • Default: 3.

installroot — string

The root of the filesystem for all packaging operations. It requires an absolute path. See also --installroot commandline option. 🏠

  • Default: /.

install_weak_deps — boolean

If enabled, when a new package is about to be installed, all packages linked by weak dependency relation (Recommends or Supplements flags) with this package will be pulled into the transaction. 🫂

  • Default: True.

keepcache — boolean

If enabled, keeps downloaded packages in the cache. If disabled cache will persist until the next successful transaction even if no packages have been installed. 💾

  • Default: False.

logdir — string

Directory where the log files will be stored. 📝

  • Regular user default: ~/.local/state.
  • Superuser default: /var/log.

log_rotate — integer

Log files are rotated log_rotate times before being removed. If log_rotate is 0, the rotation is not performed. 🔄

  • Default: 4.

log_size — storage size

Log files are rotated when they grow bigger than log_size bytes. If log_size is 0, the rotation is not performed. 📏

The size applies for individual log files, not the sum of all log files. See also log_rotate.

  • Default: 1M.

module_platform_id — string

Set this to $name:$stream to override PLATFORM_ID detected from /etc/os-release. It is necessary to perform a system upgrade and switch to a new platform. 🚀

  • Default: empty.

module_stream_switch — boolean

If enabled, allows switching enabled streams of a module. 🔀

  • Default: False.

multilib_policy — string

Controls how multilib packages are treated during install operations. ⚙️

Can either be best for the depsolver to prefer packages which best match the system's architecture, or all to install packages for all available architectures.

  • Default: best.

obsoletes — boolean

If it's switched on, DNF5 uses obsoletes processing logic — meaning it checks whether any dependencies of a given package are no longer required, and then removes them. 💅

This is lowkey a lifesaver when you're doing distribution level upgrades, bestie, fr fr.

It has effect during install/upgrade processes.

Command-line option: --obsoletes

Default: True.

optional_metadata_types 💖

Type: list

The lil menu you can pick from, and it's exactly these: comps, filelists, other, presto, updateinfo, all

This one decides which types of metadata get loaded on top of the essential primary and modules metadata — and those two are always loaded, non-negotiable, they're the main characters. 🫶 Heads up tho: individual DNF commands may extend this list at runtime.

Note: the list only includes metadata types that DNF actually recognizes. But a repository's metadata can absolutely contain other types too (e.g., AppStream, or metadata stored as databases instead of XML files). The special value all means all metadata types present in the repository, including the ones DNF has never heard of. 👑

Default: comps,updateinfo

persistdir

Type: string

The directory where DNF5 stores its persistent data between runs. It's the lil vault where the important stuff lives. 🎀

Default: /var/lib/dnf.

persistence

Type: string

Whether changes should persist across system reboots. If you pass --transient (see transient option), that overrides this setting and forces transient. Valid values are:

  • auto: changes will persist across reboots, unless the target is a running bootc system and the system is already in an unlocked state (i.e. /usr is writable).
  • transient: changes will be lost on the next reboot. Only applicable on bootc systems. Beware that changes to /etc and /var will persist, depending on the configuration of your bootc system. See also https://bootc.dev/bootc//man/bootc-usr-overlay.8.html.
  • persist: changes will persist across reboots.

Default: auto.

pluginconfpath

Type: list

A list of directories that get searched for libdnf5 plugin configurations to load. 🦋

Every configuration file found in these directories that's named the same as a plugin gets parsed.

Default: /etc/dnf/libdnf5-plugins.

pluginpath

Type: list

A list of directories that get searched for libdnf5 plugins to load. Plugins found in any of the directories in this configuration option are used. No picking favourites here, bestie. ✨

Default: /usr/lib64/libdnf5/plugins/

plugins

Type: boolean

If enabled, libdnf5 plugins are enabled. That's it, that's the whole vibe. 💅

Default: True.

protected_packages

Type: list

This append list option holds the names of packages that DNF5 should never completely remove. 🛡️

They're protected via Obsoletes as well as user/plugin removals.

An entry prefixed with glob:, such as glob:/path/to/dir/*.conf, expands to all matching files and reads one package per line from each.

Default: dnf5,glob:/etc/dnf/protected.d/*.conf.

Note: DNF5 will protect also the package corresponding to the running version of the kernel. See also the protect_running_kernel option.

protect_running_kernel

Type: boolean

Controls whether the package corresponding to the running version of the kernel is protected from removal. Your kernel said "not today" and honestly? Iconic. 👑

Default: True.

Note: YUM compatibility option

recent

Type: integer

Sets the time period, in days, that gets used for the --recent option in the repoquery, info and list commands. ⭐

Default: 7

reposdir

Type: list

Repository configuration files locations.

The behavior of reposdir could differ when it is used along with the --installroot option. (iykyk 👀)

Default: [/etc/yum.repos.d, /etc/distro.repos.d, /usr/share/dnf5/repos.d]

skip_broken

Type: boolean

If enabled, DNF5 will skip uninstallable packages instead of just failing while resolving dependencies. It's giving "we move on" energy. 🧚

Default: False.

skip_system_repo_lock

Type: boolean

Skip acquiring a lock on the system repository (equivalent to the RPM database). That lock exists to stop processes from reading the system repository while another process is running a transaction. Unprivileged users are allowed to acquire a read lock on the system repository, so skip_system_repo_lock=true may be used to ignore their lock.

skip_unavailable

Type: boolean

If enabled, DNF5 will skip unavailable packages instead of failing while preparing rpm transactions. 🌈

Default: False.

system_cachedir

Type: string

For superuser, this overwrites the cachedir option value.

It allows one to differentiate user and superuser cachedir. 💜

Default: /var/cache/libdnf5.

system_state_dir

Type: string

System state files location. See dnf5-system-state(7), system state for details. 📂

Default: /usr/lib/sysimage/libdnf5.

transaction_history_dir

Type: string

History database location.

By default it has the same value as system_state_dir.

tsflags

Type: list

A list of strings that add extra flags for the RPM transaction. Here's the whole matching-up, bestie:

  • noscripts — RPMTRANS_FLAG_NOSCRIPTS
  • test — RPMTRANS_FLAG_TEST
  • notriggers — RPMTRANS_FLAG_NOTRIGGERS
  • nodocs — RPMTRANS_FLAG_NODOCS
  • justdb — RPMTRANS_FLAG_JUSTDB
  • nocontexts — RPMTRANS_FLAG_NOCONTEXTS
  • nocaps — RPMTRANS_FLAG_NOCAPS
  • nocrypto — RPMTRANS_FLAG_NOFILEDIGEST
  • deploops — RPMTRANS_FLAG_DEPLOOPS
  • noplugins — RPMTRANS_FLAG_NOPLUGINS

The nocrypto option will also set the _RPMVSF_NOSIGNATURES and _RPMVSF_NODIGESTS VS flags.

The test option provides a transaction check without performing the transaction. It includes downloading of packages, OpenPGP keys check (including permanent import of additional keys if necessary), and rpm check to prevent file conflicts. 👀

The noplugins option disables use of rpm plugins.

Default: empty.

use_host_config

Use configuration files and variable definitions from the host system rather than the installroot. See dnf5-installroot(7) for more info. 🏠

Default: False.

usr_drift_protected_paths

Type: list

A list of paths that are likely to cause problems when their contents drift with respect to /usr, e.g. /etc/pam.d/*. If a transient transaction would modify these paths, DNF5 aborts the operation and prints an error. No cap, it just stops.

When using persistence=transient on bootc systems, a transient overlay is created on /usr, and any changes DNF5 makes to /usr will be discarded on reboot. However, other paths such as /etc and /var are (often) not backed by a transient overlay, so changes to them will persist across reboots. Usually this "filesystem drift" is fine, but it can cause problems in certain situations. For example, a configuration file in /etc that's shared by multiple packages might reference a .so file under /usr/lib64 that no longer exists. 😭

If any paths are protected by this option, DNF5 will download filelist metadata from repositories before resolving transient transactions.

An entry prefixed with glob:, such as glob:/path/to/dir/*.conf, expands to all matching files and reads one path per line from each. Both the glob pattern in the option list entry and the individual paths listed within the files (e.g. /etc/pam.d/*) may contain globs. 🌀

Default: glob:/etc/dnf/usr-drift-protected-paths.d/*.conf.

varsdir

Type: list

A list of directories where variables definition files are looked for. 🔍

See variable files in Configuration reference.

Default: /etc/dnf/vars.

zchunk

Type: boolean

If enabled, repository metadata are compressed using the zchunk format (if available). Compressed and cute. 🎀

Default: True.

✨ [MAIN] OPTIONS - COLORS ✨

okay so this is the part where you get to make your terminal look like a sunset, bestie 🌈 every one of these takes a color value, and every single one has a default so you don't even have to touch them if you don't want to. but like. you could. 💅

  • color_list_available_upgrade (color) — the color of available packages that are newer than what you've got installed. used during list operations. Default: bold,blue.
  • color_list_available_downgrade (color) — the color of available packages that are older than what you've got installed (yes, downgrades are a thing, we don't judge 🙈). used during list operations. Default: dim,magenta.
  • color_list_available_reinstall (color) — the color of available packages that are identical to the installed versions and are available for reinstalls. used during list operations. Default: bold,green.
  • color_list_available_install (color) — the color of packages that are available for installation and none of their versions is installed. used during list operations. Default: bold,cyan.
  • color_update_installed (color) — the color of removed packages. this one is used while displaying transactions. Default: dim,red.
  • color_update_local (color) — the color of local packages that are installed from the @commandline repository. used while displaying transactions. Default: dim,green.
  • color_update_remote (color) — the color of packages that are installed/upgraded/downgraded from remote repositories. used while displaying transactions. Default: bold,green.
  • color_search_match (color) — the color of the patterns matched in search output. Default: bold,magenta.

🎀 REPO OPTIONS 🎀

these are the options that live on a per-repository basis, iykyk. every repo can vibe differently 🦋

  • baseurl (list) — list of URLs for the repository. Default: []. URLs are tried in the listed order (equivalent to yum's "failovermethod=priority" behaviour).
  • cost (integer) — the relative cost of accessing this repository, defaulting to 1000. this value is compared when the priorities of two repositories are the same. the repository with the lowest cost is the one that gets picked. it's useful for making the library prefer on-disk repositories over remote ones.
  • enabled (boolean) — include this repository as a package source. Default: True.
  • gpgkey (list) — URLs of OpenPGP key files that can be used for signing metadata and packages of this repository. if a file can not be verified using the already imported keys, import of keys from this option is attempted and the keys are then used for verification. Default: [].
  • metalink (string) — URL of a metalink for the repository. Default: None.
  • mirrorlist (string) — URL of a mirrorlist for the repository. Default: None.
  • name (string) — a human-readable name of the repository. defaults to the ID of the repository.
  • priority (integer) — the priority value of this repository. if there's more than one candidate package for a particular operation, the one from a repo with the lowest priority value is picked, possibly despite being less convenient otherwise (e.g. by being a lower version). Default: 99.
  • type (string) — type of repository metadata. supported values are: rpm-md. aliases for rpm-md: rpm, repomd, rpmmd, yum, YUM. Default: empty.

🦋 SOURCE AND DEBUGINFO REPOSITORY NAMES 🦋

okay so the naming convention here is so satisfying once you see it, bestie, it's giving pattern recognition 🌸

for a given repository with an identifier in the form "<ID>-rpms", its corresponding source repository is expected to have an identifier in the form "<ID>-source-rpms" and debuginfo repository an identifier in the form "<ID>-debug-rpms". otherwise (if the repository identifier doesn't have the "-rpms" suffix), the source repository is expected to have an identifier in the form "<ID>-source" and debuginfo repository an identifier in the form "<ID>-debuginfo".

for example, for repository "fedora", the source repository is "fedora-source" and debuginfo repository is "fedora-debuginfo". for repository "fedora-rpms", the source repository is "fedora-source-rpms" and debuginfo repository is "fedora-debug-rpms".

🌸 REPO VARIABLES 🌸

the right side of every repo option can be enriched by these variables, and honestly this is the part that makes your .repo files feel ✨alive✨

  • $arch — refers to the system's CPU architecture e.g, aarch64, i586, i686 and x86_64.
  • $basearch — refers to the base architecture of the system. for example, i686 and i586 machines both have a base architecture of i386, and AMD64 and Intel64 machines have a base architecture of x86_64.
  • $releasever — refers to the release version of operating system which DNF5 derives from information available in RPMDB.

in addition to these hard coded variables, user-defined ones can also be used 💜 they can be defined either via variable files, or by using special environmental variables. the names of these variables must be prefixed with DNF_VAR_ and they can only consist of alphanumeric characters and underscores:

$ DNF_VAR_MY_VARIABLE=value

to use such variable in your repository configuration remove the prefix. e.g.:

[myrepo]
baseurl=https://example.site/pub/fedora/$MY_VARIABLE/releases/$releasever
🚨 note that it is not possible to override the arch and basearch variables using either variable files or environmental variables. periodt.

although users are encouraged to use named variables, the numbered environmental variables DNF0 - DNF9 are still supported:

$ DNF1=value

[myrepo]
baseurl=https://example.site/pub/fedora/$DNF1/releases/$releasever

💜 OPTIONS FOR BOTH [MAIN] AND REPO 💜

some options can be applied in either the main section, per repository, or in a combination. the value provided in the main section is used for all repositories as the default value, which repositories can then override in their configuration. so like, main is the group chat default and each repo can go off and do its own thing 🫶

  • bandwidth (storage size) — total bandwidth available for downloading, in bytes per second. used for both metadata and package downloads. this value is only used when the throttle option is set as a percentage. when throttle is set as an absolute value, bandwidth is ignored. Default: 0 (no limit).
  • build_cache (boolean) — if enabled, DNF5 will save libsolv cache generated from downloaded metadata to cachedir. these solv files are loaded during subsequent runs which significantly speeds up DNF5. Default: True.
  • countme (boolean) — when enabled, one (and only one) HTTP GET request for the metalink file will be selected at random every week to carry a special URL flag.

this flag allows the repository provider to estimate the number of systems consuming the repository, by counting such requests over a week's time. this method is more accurate than just counting unique IP addresses (which is subject to both overcounting and undercounting due to short DHCP leases and NAT, respectively).

this is not an out-of-band HTTP request made for this purpose alone. only requests initiated by DNF during normal operation, such as to check for metadata updates, can get this flag.

the flag is a simple "countme=N" parameter appended to the metalink URL where N is an integer representing the age "bucket" this system belongs to. four buckets are defined, based on how many full weeks have passed since the installation of a system:

  • bucket 1 — system age: first week
  • bucket 2 — system age: first month (2 - 4 weeks)
  • bucket 3 — system age: first 6 months (5 - 24 weeks)
  • bucket 4 — system age: more than 6 months (> 24 weeks)

this number is meant to help distinguish short-lived (throwaway) machines from long-term installs and get a better picture of how systems are used over time.

to determine a system's installation time ("epoch"), the machine-id(5) file's modification time is used as the single source of truth. this file is semantically tied to the system's lifetime as it's typically populated at installation time or during the first boot by an installer tool or init system (such as systemd(1)), respectively, and remains unchanged.

if the file is empty or missing (such as in containers), the time of the very first request made using the expanded metalink URL (i.e. with any repository variables such as $releasever substituted) that carried the flag is declared as the epoch.

if no metalink URL is defined for this repository but a mirrorlist URL is, the latter is used for this purpose instead.

Default: False.

  • disable_excludes (list) — used to disable package, group and environment filtering. it can include a list of repository IDs (globs allowed) for which repository-specific package excludes are ignored. if it contains the special value main, excludes from the main configuration files are bypassed. if it contains the special value *, no excludes filtering is applied at all. 🔥
  • enablegroups (boolean) — if enabled, DNF5 will allow the use of package groups. Default: True.
  • excludepkgs (list) — exclude packages of this repository, specified by a name or a glob and separated by a comma, from all operations. can be disabled using disable_excludes config option. Default: [].
  • fastestmirror (boolean)
🫶 and that's exactly where part 3 runs out of breath, bestie — fastestmirror is literally mid-sentence and part 4 picks it right back up. no cap.

If it's switched on, TCP socket latency is used to find the closest available mirror. A mirror is then selected at random with less than twice the lowest latency for load balancing purposes. This overrides the order provided by the mirrorlist/metalink file itself, and does not take into consideration mirrorlist parameters such as mirror bandwidth nor preferred mirrors for client IP addresses.

  • Default: False.
  • pkg_gpgcheck (boolean) — do we OpenPGP signature check the packages hanging out in this repo? That's the whole question. 💅
    • Default: False.
    • Heads up bestie: this doesn't apply for packages passed directly as arguments, because those aren't in any repository at all. For those, go look at localpkg_gpgcheck.
  • includepkgs (list) — a name-or-glob list, comma separated, of packages from this repository to include in all operations.

It's the inverse of excludepkgs — DNF5 will exclude any package in the repo that doesn't match this list.

It works in conjunction with excludepkgs and doesn't override it. So if you do excludepkgs=*.i386 and includepkgs=python*, then only packages starting with python that do not have an i386 arch will be seen by DNF5 in this repo. Periodt.

Can be disabled using the disable_excludes config option.

  • Default: [].
  • ip_resolve (ip address) — how DNF5 resolves host names. Set it to 4, IPv4, 6, IPv6 to resolve to IPv4 or IPv6 addresses only. Pick your fighter. 🥊
    • Default: whatever.
  • localpkg_gpgcheck (boolean) — if enabled, DNF5 will perform an OpenPGP signature check on local packages (packages in a file, not in a repository). 🍓
    • Default: False.
  • max_parallel_downloads (integer) — maximum number of simultaneous downloads. Max is 20.
    • Default: 3.
  • max_downloads_per_mirror (integer) — maximum number of simultaneous downloads per mirror. Max is 20.
    • Default: 3.
  • metadata_expire (time in seconds) — the period after which the remote repository gets checked for a metadata update, and if the vibe says yes, the local metadata cache is updated. It can be -1 or never to make the repo never considered expired.

Expire of metadata can also be triggered by a change of timestamp of configuration files (dnf.conf, <repo>.repo).

See also check_config_file_age.

  • Default: 60 * 60 * 48, 48 hours.
  • minrate (storage size) — sets the low speed threshold in bytes per second. If the server is sending data at the same or slower speed than this value for at least timeout option seconds, DNF5 aborts the connection. Not me hanging up on a slow server 😭
    • Default: 1000.
  • password (string) — the password used to connect to a repository with basic HTTP authentication.
    • Default: empty.
  • proxy (string) — URL of a proxy server to connect through.

Set to an empty string in the repository configuration to disable the proxy setting inherited from the main section. The expected format of this option is <scheme>://<ip-or-hostname>[:port]. (For backward compatibility, _none_ can be used instead of the empty string.)

  • Default: empty.
  • > Note: the curl environment variables (such as http_proxy) are effective if this option is unset (or _none_ is set in the repository configuration). See the curl man page for details.
  • proxy_username (string) — the username to use for connecting to the proxy server.
    • Default: empty.
  • proxy_password (string) — the password to use for connecting to the proxy server.
    • Default: empty.
  • proxy_auth_method (string) — the authentication method used by the proxy server. Valid values are:
    • basic — HTTP Basic authentication
    • digest — HTTP Digest authentication
    • negotiate — HTTP Negotiate (SPNEGO) authentication
    • ntlm — HTTP NTLM authentication
    • digest_ie — HTTP Digest authentication with an IE flavor
    • ntlm_wb — NTLM delegating to winbind helper
    • none — None auth method
    • any — All suitable methods
    • Default: any.
  • proxy_sslcacert (string) — path to the file containing the certificate authorities to verify proxy SSL certificates.
    • Default: empty, uses system default.
  • proxy_sslclientcert (string) — path to the SSL client certificate used to connect to proxy server.
    • Default: empty.
  • proxy_sslclientkey (string) — path to the SSL client key used to connect to proxy server.
    • Default: empty.
  • proxy_sslverify (boolean) — if enabled, proxy SSL certificates are verified. If the client can not be authenticated, connecting fails and the repository is not used any further. If False, SSL connections can be used, but certificates are not verified. 🙈
    • Default: True.
  • repo_gpgcheck (boolean) — if enabled, DNF5 will perform an OpenPGP signature check on this repository's metadata.
    • Default: False.
    • > Note: OpenPGP keys for this check are stored separately from OpenPGP keys used in package signature verification. Furthermore, they are also stored separately for each repository.
This means that DNF5 may ask to import the same key multiple times. For example, when a key was already imported for package signature verification and this option is turned on, it may be needed to import it again for the repository. The way that it makes you re-import the same key 😭 iconic behavior honestly.
  • skip_if_unavailable (boolean) — if enabled, DNF5 will continue running and disable the repository that couldn't be synchronized for any reason. This option doesn't affect skipping of unavailable packages after dependency resolution. To check inaccessibility of repository, use it in combination with the refresh command line option <# refresh-option-label>.
    • Default: False.
    • > Note: this option in particular can be overridden by a distribution-specific configuration. For more details see drop-in configuration directories.
  • sslcacert (string) — path to the file containing the certificate authorities to verify SSL certificates.
    • Default: empty, uses system default.
  • sslclientcert (string) — path to the SSL client certificate used to connect to remote sites.
    • Default: empty.
  • sslclientkey (string) — path to the SSL client key used to connect to remote sites.
    • Default: empty.
  • sslverify (boolean) — if enabled, remote SSL certificates are verified. If the client can not be authenticated, connecting fails and the repository is not used any further. If disabled, SSL connections can be used, but certificates are not verified.
    • Default: True.
  • throttle (storage size) — limits the downloading speed, in bytes per second. Applied to both metadata and package downloads. It can be an absolute value (e.g. 5M for 5 MiB/s) or a percentage (e.g. 60%). When given as a percentage, the actual speed limit is calculated relative to the bandwidth option value. 0 means no throttling. The resulting speed limit must not be lower than minrate.
    • Default: 0.
  • timeout (time in seconds) — number of seconds to wait for a connection before timing out. Used in combination with minrate option option.
    • Default: 30.
  • username (string) — the username to use for connecting to repo with basic HTTP authentication.
    • Default: empty.
  • user_agent (string) — the User-Agent string to include in HTTP requests sent by DNF5. 🦋
    • Default:
libdnf (NAME VERSION_ID; VARIANT_ID; OS.BASEARCH)
  • > Note: NAME, VERSION_ID and VARIANT_ID are OS identifiers read from the os-release(5) file, and OS and BASEARCH are the canonical OS name and base architecture, respectively. Example:
libdnf (Fedora 39; server; Linux.x86_64)

✨ TYPES OF OPTIONS ✨

Okay bestie, before you go wild in the config files, you gotta know what kind of values each option will actually accept. Vibe check your data types, fr fr 💅

  • boolean — the iconic two-option queen. Only two possible values exist here, no in-between, no "it's complicated."

You can use one of these: 1, 0, True, False, yes, no.

  • color — a string that describes a color plus modifiers, all comma-separated, like red,bold.
    • Colors: black, blue, cyan, green, magenta, red, white, yellow.
    • Modifiers: bold, blink, dim, normal, reverse, underline.
  • integer — a whole number. Written without a fractional component, so no decimal drama allowed 🚫
  • ip address type — a string describing ip address types.

One of these can be used: 4, IPv4, 6, IPv6.

  • list — a string that's secretly one or more strings, separated by space or comma characters. The backslash '\' can escape any character, which lets you include it literally inside an individual string. Sneaky but slay.

Example: 'item1,item2\,with\,commas,item3\ with\ spaces item4'

  • storage size — a string for storage sizes in bytes, formed by an integer plus a unit.

Valid units are k, M, G.

  • string — a sequence of symbols or digits with no whitespace character anywhere in it. Keep it tight.
  • time in seconds — a string representing time units in seconds. Can be set to -1 or never. (So yes, you can literally say "never" and the config will understand. Main character energy.)

🗂️ DROP-IN CONFIGURATION DIRECTORIES 🗂️

DNF5 loads configuration options that are defined in the main configuration file, user configuration files and distribution configuration files. Three sources, one truth. Let's go 🌈

The configuration files are processed following this order:

  1. Configuration files are alphabetically sorted in a list of names from the distribution configuration directory and the user configuration directory. If a file with the same name is present in both directories, only the file from the user configuration directory is added to the list. The distribution file is then masked by the user file. (User file said "not today" 💅)
  2. Options are retrieved in order from the list. The configuration from the next file overrides the previous one. The last option wins. Periodt.

Example of configuration files

User configuration files:

  • /etc/dnf/dnf.conf
  • /etc/dnf/libdnf5.conf.d/20-user-settings.conf
  • /etc/dnf/libdnf5.conf.d/60-something.conf
  • /etc/dnf/libdnf5.conf.d/80-user-settings.conf

Distribution configuration files:

  • /usr/share/dnf5/libdnf.conf.d/50-something.conf
  • /usr/share/dnf5/libdnf.conf.d/60-something.conf
  • /usr/share/dnf5/libdnf.conf.d/90-something.conf

Resulting file loading order by default

(/usr/share/dnf5/libdnf.conf.d/60-something.conf is skipped, masked by the user file /etc/dnf/libdnf5.conf.d/60-something.conf):

  1. /etc/dnf/libdnf5.conf.d/20-user-settings.conf
  2. /usr/share/dnf5/libdnf.conf.d/50-something.conf
  3. /etc/dnf/libdnf5.conf.d/60-something.conf
  4. /etc/dnf/libdnf5.conf.d/80-user-settings.conf
  5. /usr/share/dnf5/libdnf.conf.d/90-something.conf
  6. /etc/dnf/dnf.conf

Files and directories

  • User Configuration Directory — /etc/dnf/libdnf5.conf.d/
  • User Configuration Files — /etc/dnf/libdnf5.conf.d/20-user-settings.conf
  • Distribution Configuration Directory — /usr/share/dnf5/libdnf.conf.d/
  • Distribution Configuration Files — /usr/share/dnf5/libdnf.conf.d/50-something.conf

🦋 DROP-IN REPO DIRECTORIES 🦋

After the repository configurations are loaded, other repo configurations can be overloaded from the directories user repos override directory and distribution repos override directory. Round two, but for repos ✨

The format of the files inside the directories is the same as the format of the repository configuration files. The options in the overridden files can modify existing repos but cannot create new repositories. Sorry babe, no making new repos here.

Override files support globs in the repository ID in order to support bulk modifications of repository parameters. Bulk edits are so efficient, we love to see it 🫶

The repository overrides are processed following this order:

  1. Files from /usr/share/dnf5/repos.override.d/ and /etc/dnf/repos.override.d/ are loaded in an alphabetically sorted list. In case files have the same name, the file from /etc/dnf/repos.override.d/ is used. This implies the list has only unique filenames. This also implies that the repository configuration files can be simply masked by creating a file with the same name in the /etc override directory.
  2. The options from the files are applied in the order they are loaded. The last option wins.
Note: See also the documentation for Config-manager Command to see where the overrides are used.

Example configuration

# Enable `skip_if_unavailable` for all repositories
[*]
skip_if_unavailable = true

# And then disable `skip_if_unavailable` for repositories with id prefix "fedora"
[fedora*]
skip_if_unavailable = false

Example of configuration files

This example shows the order in which override files are processed.

Files with user repos overrides:

  • /etc/dnf/repos.override.d/20-user-overrides.repo
  • /etc/dnf/repos.override.d/60-something2.repo
  • /etc/dnf/repos.override.d/80-user-overrides.repo
  • /etc/dnf/repos.override.d/99-config-manager.repo

Files with distribution repos overrides:

  • /usr/share/dnf5/repos.override.d/50-something2.repo
  • /usr/share/dnf5/repos.override.d/60-something2.repo
  • /usr/share/dnf5/repos.override.d/90-something2.repo

Resulting file processing order:

  1. /etc/dnf/repos.override.d/20-user-overrides.repo
  2. /usr/share/dnf5/repos.override.d/50-something2.repo
  3. /etc/dnf/repos.override.d/60-something2.repo
  4. /etc/dnf/repos.override.d/80-user-overrides.repo
  5. /usr/share/dnf5/repos.override.d/90-something2.repo
  6. /etc/dnf/repos.override.d/99-config-manager.repo

Files and directories

  • User Repos Override Directory — /etc/dnf/repos.override.d/
  • User Repos Override Files — /etc/dnf/repos.override.d/20-user-overrides.repo
  • Distribution Repos Override Directory — /usr/share/dnf5/repos.override.d/
  • Distribution Repos Override Files — /usr/share/dnf5/repos.override.d/50-something2.repo

📁 FILES 📁

  • Main Configuration File — /etc/dnf/dnf.conf
  • Cache Files — /var/cache/libdnf5
  • Repository Files — /etc/yum.repos.d/
  • Variables — Any property named file in /etc/dnf/vars is turned into a variable named after the filename (or overrides any of the above variables but those set from commandline). Filenames may contain only alphanumeric characters and underscores and be in lowercase. Variables are also read from /etc/yum/vars for YUM compatibility reasons. Nostalgic but make it functional 💜

🎀 DIRECTORIES 🎀

Repository Directories

Directories are listed in the order in which they are processed.

Note: Unlike overrides that modify an existing repository configuration, the configuration in these directories defines new repositories. It is not possible to define repositories with the same ID. If multiple repositories with the same ID are defined only the first configuration will be loaded. Loading the next one will log an error. So like, don't do that 🙈
  • YUM Repositories Directory — /etc/yum.repos.d/
  • Distribution Repositories Directory in /etc — /etc/distro.repos.d/
  • Distribution Repositories Directory in /usr — /usr/share/dnf5/repos.d/

Variables Directories

  • Variables Directory — /etc/dnf/vars/
  • Distribution Variables Directory — /usr/share/dnf5/vars.d/

👀 SEE ALSO 👀

Author

See AUTHORS.md in dnf5 source distribution.

Contributors to the dnf5 project.

And that's a wrap bestie, you made it to the end of the whole page 🏁💖 This one was dated Sep 24, 2026 and it's DNF5.CONF(5) — go forth and configure your heart out, you absolute icon 👑

📦 where this page comes from