ZYPP.CONF(5)

🎀 zypp.conf 💅

(from the LIBZYPP File Formats Manual)

✨ NAME ✨

Okay so zypp.conf is the general configuration file for libzypp based package management tools. Main character config energy, fr fr.

🦋 SYNOPSIS 🦋

System configuration files:

/etc/zypp/zypp.conf
/etc/zypp/zypp.conf.d/*.conf.

Vendor configuration files:

/usr/etc/zypp/zypp.conf
/usr/etc/zypp/zypp.conf.d/*.conf.

💖 DESCRIPTION 💖

These files hold the basic configuration data for libzypp — that’s the package management library used by processes like e.g. zypper(8), YAST(8) or PackageKit’s zypp backend. Bestie, it’s kind of a big deal. 💅

Many configuration values can be amended by processes according to command line options or other needs. Otherwise, the values defined here are used as the default. When these files do not specify a particular parameter, libzypp’s builtin defaults are used. ✨

The file format supports multiple sections, and each section can contain multiple key-value assignments. A section is introduced by a line containing the section name enclosed in square brackets, like:

[name]

A key-value assignment is a single line that has the name of the key, an equals sign, and a setting for the value, like:

key = vlaue

Leading and trailing whitespace is ignored, as is whitespace surrounding the equals sign. 🫶

Note: key-value assignments outside any section are bound to an unnamed section and may not be recognized. Not me trusting an unnamed section, bestie. 🙈

Lookup of section and key names is case-sensitive. 🔍

Any line starting with # is ignored, as is any blank line.

Where a Boolean value is expected, any of 1, 0, yes, no, on, off, true or false can be used. Comparisons here are case-insensitive. 🎀

See the FILES section to learn how the different configuration files are merged. We’d recommend maintaining the system configuration by using drop-in files in /etc/zypp/zypp.conf.d/ rather than overriding the vendor configuration with an own /etc/zypp/zypp.conf. But both is possible. Just make sure your /etc/zypp/zypp.conf contains appropriate settings for the keys defined in /usr/etc/zypp/zypp.conf. At the time of this writing these are just multiversion and multiversion.kernels. 🌸

🌈 SECTIONS 🌈

The following sections are known, and can contain the given key assignments. Libzypp’s builtin default value for a key is given in parenthesis, like:

key (value)

For some keys there is no fix builtin default value, but the best value is chosen according to the concrete task to be performed. While it is possible to prescribe a fix value, it’s often the best decision not to define this key at all. This is indicated by showing <UNSET> as the default value, like:

key (<UNSET>)

Many of the defaults set here can be overridden via zypper command line options. This is especially true for the resolver related defaults. See the zypper(8) man page for more details. 👑

👑 [main] 👑

• lock_timeout (0 sec) — if zypp is locked by another process, this is the number of seconds to wait for the lock to become available. If the lock can not be acquired within the specified time, an exception is raised. A negative value will wait forever. 😭

The environment variable ZYPP_LOCK_TIMEOUT can be used to override this setting. ZYPP_LOCK_TIMEOUT=-1 is sometimes set by unattended running scripts to delay a zypper command rather than failing if the lock is not available. 🫶

• cachedir (/var/cache/zypp) — path where the caches are kept.
• metadatadir ({cachedir}/raw) — path where the downloaded repo metadata are kept.
• solvfilesdir ({cachedir}/solv) — path where the repo .solv file caches are kept.
• packagesdir ({cachedir}/packages) — path where the downloaded packages are kept.
• configdir (/etc/zypp) — path where the remaining configuration files are kept.
• reposdir ({configdir}/repos.d) — path where the known repositories .repo files are kept.
• servicesdir ({configdir}/services.d) — path where the known services .service files are kept.
• varsdir ({configdir}/vars.d) — path where custom repo variable definitions are kept.

A custom repo variable is defined by creating a file inside the varsdir directory. The variable name equals the file name. The file’s first line (up to, but not including, the newline character) defines the variable’s value. See section Variable substitution in the zypper(8) man page for more details. 🧚

• vendordir ({configdir}/vendors.d) — path where vendor equivalence description files are kept.

Each file in this directory defines a comma-separated list of equivalent vendor string prefixes (case-insensitive comparison):

-------------------- file begin ----------------
[main]
vendors = MyVendor,AlternateName
-------------------- file end ------------------

By this, vendor strings starting with "MyVendor" or "AlternateName" are considered to be equivalent. Packages from equivalent vendors may replace each other without being considered as a vendor change. ✨

Note: within the "opensuse*" namespace, exact matches (case-insensitive) are required. "vendors = suse,opensuse" will allow switching between "suse*" and "opensuse", but not e.g. "opensuse build service". 💀

• repo.add.probe (false) — whether repository URLs should be probed when added (e.g. via zypper addrepo). If false, the repository URL is checked upon the first refresh.
• repo.refresh.delay (10 min) — the amount of time in minutes that must pass before another repo auto-refresh is attempted. ⏳

A value of 0 means the repository will always be checked. To get the opposite effect, disable autorefresh for the repository. This option has no effect for explicitly user-requested refresh requests.

• repo.refresh.locales (en) — a list of locales for which translated package descriptions should be downloaded in case they are available and the repo supports this. Not all repo formats support downloading specific translations only. 🌍

The concrete list is in fact controlled via zypper’s locales, addlocale and removelocale commands. The locales defined here are just sticky. 🍓

• download.max_concurrent_connections (5) — maximum number of concurrent connections to use per transfer.
• download.min_download_speed (0 B/sec) — sets the minimum download speed (in Byte per second) until the connection is dropped. 0 means no limit. 🔥

This can be useful to prevent security attacks on hosts by providing updates at very low speeds.

• download.min_download_speed_time (60 sec) — sets the time in seconds that the transfer speed must remain below download.min_download_speed before the transfer is aborted.
• download.max_download_speed (0 B/sec) — sets the maximum download speed (in Byte per second). 0 means no limit.
• download.max_silent_tries (1) — [Beware!] the number of media backend internal attempts to download a file from a server before reporting an error back to the application if failing. Setting this to 0 will silently retry forever! It’s mainly used in some CI and Test environments but actually makes little sense in real life. 🫠
• download.connect_timeout (60 sec) — maximum time in seconds that you allow the connection phase to the server to take. This timeout only limits the connection phase, it has no impact once libcurl has connected. ⏱️
• download.transfer_timeout (180 sec) — maximum time in seconds that you allow a transfer operation to take. This is useful for preventing your batch jobs from hanging for hours due to slow networks or links going down. Limiting operations to less than a few minutes risks aborting perfectly normal operations. 😭
• download.use_deltarpm (false) (true on SUSE-15.6 and older) — [Legacy!] whether to consider using a .delta.rpm when downloading a package. If your network connection is not too slow, you may benefit from explicitly disabling .delta.rpm usage on SUSE-15.6 and older. Newer distributions do no longer offer .delta.rpms at all, so the default was changed to prevent overhead.
• download.use_deltarpm.always (false) — [Legacy!] whether to consider using a .delta.rpm even if the full .rpm is locally available. This option has no effect unless download.use_deltarpm is set true. Used for testing only.
• download.media_preference (download) — hint which media to prefer when installing packages (download vs. volatile aka. CD/DVD).

Note that this is just a hint. First of all, the solver will choose the best package according to its repos priority, version and architecture. But if there is a choice, we will prefer packages from the desired media. 🎯

Packages available locally are always preferred. The question is whether you prefer packages being downloaded via FTP/HTTP/HTTPS (download), rather than being prompted to insert a CD/DVD (volatile), in case they are available on both media.

• download.media_mountdir (/var/adm/mount) — path where media are preferably mounted or downloaded. 💾

The media backend will try to organize media mount points and download areas below this directory, unless a different location is requested by the application. If the directory is not accessible and read/writable for a specific user, the fallback is to use /var/tmp.

• download.use_geoip_mirror (true) — whether to use the geoip feature of download.opensuse.org. 🌐

The media backend may rewrite download requests to the geographically closest available mirror. Which exact mirror is used will be determined by requesting a "geoip" file from download.opensuse.org via a HTTP GET request to https://download.opensuse.org/geoip, the server will use the client’s IP to determine the closest mirror if available.

Some specific files are however excluded from this redirection due to security reasons, especially the repo metadata index and its key and checksum files: repomd.xml{,.key,.asc}. 🔐

• gpgcheck (on) — default signature checking of repo metadata and downloaded rpm packages.
• repo_gpgcheck (<UNSET>, depending on {gpgcheck}) — part of the same default signature-checking setup for repo metadata; its <UNSET> value depends on {gpgcheck}.
• pkg_gpgcheck (<UNSET>, depending on {gpgcheck}) — part of the same default signature-checking setup for downloaded rpm packages; its <UNSET> value depends on {gpgcheck}.

Note: explicitly setting gpgcheck, repo_gpgcheck and/or pkg_gpgcheck in a repositories .repo file will overwrite these defaults for this specific repo. The zypper addrepo and modifyrepo commands provide several gpgcheck related options to tune the behavior. See the zypper(8) man page for details. 💅

If gpgcheck is on (the recommended default), we will check the signature of repo metadata. Using unsigned repos needs to be confirmed. ✅

Okay so, packages from signed repos are accepted if their checksum matches the checksum stated in the repo metadata. 💅

Packages from unsigned repos need a valid gpg signature. Using unsigned packages needs to be confirmed.

The above default behavior can be tuned by explicitly setting repo_gpgcheck and/or pkg_gpgcheck. But in general it’s recommended to relax the settings on a per repo basis, rather than relaxing the global defaults. Like, keep the global vibe strict and handle exceptions locally, iykyk:

• repo_gpgcheck = on is the same as the default behavior.
• repo_gpgcheck = off will silently accept unsigned repos. It will NOT turn off signature checking on the whole. Nevertheless, it’s not a secure setting.
• pkg_gpgcheck = on will enforce the package signature checking and the need to confirm unsigned packages for all repos (signed and unsigned).
• pkg_gpgcheck = off will silently accept unsigned packages. It will NOT turn off signature checking on the whole. Nevertheless, it’s not a secure setting.

If gpgCheck is off (not recommended), no checks are performed. You can still enable them individually by setting repo_gpgcheck and/or pkg_gpgcheck to on.

DISABLING GPG CHECKS IS NOT RECOMMENDED. Signing data enables the recipient to verify that no modifications occurred after the data were signed. Accepting data with no, wrong or unknown signature can lead to a corrupted system and in extreme cases even to a system compromise. 🫶 This is not the vibe.

---

• commit.downloadMode (<UNSET>) — the default commit package download policy to use. If the value is not set, empty or unknown, we pick some sane default depending on the task to perform. There should be little need to set a fix default here.
  • DownloadInAdvance: First download all packages to the local cache. Then start to install. This is the safe and preferred default when installing packages to the local system.
  • DownloadInHeaps: Similar to DownloadInAdvance, but try to split the transaction into heaps, where at the end of each heap a consistent system state is reached.
  • DownloadAsNeeded: Alternating download and install. Packages are cached just to avoid CD/DVD hopping. This mode saves disk space but is error prone if packages can not be retrieved in the middle of the transaction. It is an option for chroot installs, but not for the local system.
• solver.focus (<UNSET>) — the solver’s general attitude when resolving jobs. If the value is not set, empty or unknown, we use the resolver’s default.
  • Job: Focus on installing the best version of the requested packages. Add missing dependencies as needed. This is the solver’s default.
  • Installed: Focus on applying as little changes to the installed packages as needed. Choosing an older version of a package is valid if its dependencies require less changes to the system.
  • Update: Focus on updating requested packages and their dependencies as much as possible.
• solver.onlyRequires (false) — whether only required packages should be selected by the resolver. Otherwise also recommended packages are considered.
• solver.allowVendorChange (false) — [Expert Only!] Per default the solver will not replace packages of different vendors, unless you explicitly ask to do so. Setting this option to true will disable this vendor check. Packages will then be considered based on repository priority and version only. This may easily break dependent packages because different vendors may use different default settings or version schemata. 😭
• solver.dupAllowDowngrade (true) — one of the dup defaults. 👀
• solver.dupAllowNameChange (true) — one of the dup defaults. 👀
• solver.dupAllowArchChange (true) — one of the dup defaults. 👀
• solver.dupAllowVendorChange (false) — one of the dup defaults. 👀

These four are [Expert Only!] and they’re the resolver’s distribution upgrade (dup) job defaults for package version downgrades, renames, architecture changes and vendor protection. They’re different from ordinary install and update jobs. It’s not recommended to amend these defaults without need. In case of doubt zypper(8) provides command line options to do this for a specific job only.

• solver.cleandepsOnRemove (false) — [Expert Only!] Cleanup when deleting packages. Whether the solver should per default try to remove packages exclusively required by the ones it’s asked to delete.

This option should be used on a case by case basis, enabled via command line options or switches the applications offer. Changing the global default on a system where unattended actions are performed may easily damage your system. 💀

• solver.noUpdateProvide (false) — [Expert Only!] In general, packages that obsolete another package are treated as update candidates for the obsoleted package. However, SUSE-specific update rules prefer candidates that also explicitly provide the obsoleted package.

Sometimes it is necessary or helpful to disable this rule.

• solver.checkSystemFile (/etc/zypp/systemCheck) — this file contains requirements and conflicts which fulfill the needs of a running system. For example the system would be broken if no glibc or kernel is installed. The resolver is always aware of these constraints and watches they are not violated.

Each line in the file represents one dependency: requires:kernel or requires:glibc.

• solver.checkSystemFileDir ({configdir}/systemCheck.d) — path where checkSystem file drop-ins can be placed. Files are read in lexicographic order of their filenames. See solver.checkSystemFile.
• solver.upgradeTestcasesToKeep (2) — when committing a dist upgrade (e.g. zypper dup) a solver testcase is written to /var/log/updateTestcase-<date>. This testcase is often requested in bugreports regarding migrations or distribution upgrades. This option defines the number of testcases to keep on the system. Old cases will be deleted, as new ones are created. Use 0 to write no testcase at all, or -1 to keep all testcases.
• solver.upgradeRemoveDroppedPackages (true) — whether a dist upgrade should remove a product’s dropped packages.

A new product may suggest a list of old and no longer supported packages (dropped packages). Performing a dist upgrade the solver may try to delete them, even if they do not cause any dependency problems.

See also zypper dup --remove-orphaned, which provides a similar kind of cleanup. It cleans no longer required packages which are also no longer provided by any enabled repository (aka. orphaned packages).

• multiversion (<EMPTY>) [provides:multiversion(kernel) via vendor configuration] — comma separated list of packages which are built to be, and should be, installed in different versions at the same time. 🌈

Packages are selected either by name, or by provides. In the latter case the string must start with "provides:" immediately followed by the capability.

[Beware!] While it is safe to remove the definition here, the kernel will be treated like any other package then. Be very careful when adding definitions. If you add packages which are not built to support being installed in multiple versions, the packages will easily damage each other.

• multiversiondir ({configdir}/multiversion.d) — path where multiversion file drop-ins can be placed. Files are read in lexicographic order of their filenames. See multiversion.
• multiversion.kernels (<EMPTY>) [latest,latest-1,running via vendor configuration] — comma separated list of kernel packages to keep in the system if zypper purge-kernels is called and multiversion is set for the kernel packages. Kernel packages can be specified as:
  • 2.6.32.12-0.7 — an exact kernel version to keep
  • latest — keep kernel with the highest version number
  • latest-N — keep kernel with the Nth highest version number
  • running — keep the running kernel
  • oldest — keep kernel with the lowest version number
  • oldest+N — keep kernel with the Nth lowest version number

If no value is specified, no kernel will be purged.

• locksfile.path ({configdir}/locks) — the file holding the applied package locks. See the zypper(8) locks, addlock and removelock commands for more details.
• locksfile.apply (true) — whether to apply locks stored in the locksfile file at start.
• update.messages.notify (<EMPTY>) — upon their installation packages may leave an update message file in /var/adm/update-messages. At the end of each commit, zypp may collect those messages and send a notification to the user.

zypp will prepare the update messages according to the selected content format and pipe the content to the specified command.

Format:

• single — For each update message invoke the command and send the message.
• none — For each update message invoke the command but don’t use a pipe to send any data. You probably want to pass the message file on the commandline using %P (see Substitutions below).
• digest — Single invocation of the command, sending the path names of all update message. One per line.
• bulk — Single invocation of the command, sending the concatenated content of all update messages, separated by Ctrl-L.

Substitutions:

• %p — Package identification (Name-Version-Release.Arch_)
• %P — Full path to the update message file

Valid values:

The value is specified as format | command. An empty value will turn off any notification.

Examples:

single | mail -s "Update message from %p" root
none   | my-send-script -f %P

• rpm.install.excludedocs (false) — don’t install any files which are marked as documentation. See the rpm(8) --excludedocs option for details.

This is often used when building container images to save disk space. 🎀

• history.logfile (/var/log/zypp/history) — location of the history log file. The history log contains an abstract of the install actions performed by libzypp and also collects any screen output of packages during their installation, in case you want to review it.
• credentials.global.dir ({configdir}/credentials.d) — global credentials directory path.

If an URL contains a ?credentials=<filename> parameter, the credentials will be stored and looked for in a file named <filename> in this directory.

• credentials.global.file ({configdir}/credentials.cat) — global credentials catalog file path.

like, this file can totally contain a catalog of user credentials that aren't stored via the ?credentials=<filename> URL parameter (peep credentials.global.dir for that one) 👀

the file gets read if it exists, but new credentials usually get stashed in the user's home directory (~/.zypp/credentials.cat). default behavior stays winning ✨

arch (<UNSET>)

[_Expert Only!] bestie please only touch this if you genuinely know what you're doing, i'm so serious 😭

it overrides the autodetected system architecture. sometimes people use it for testing, but honestly there's no real use case unless the autodetection would fail. it's giving "break glass in case of emergency" 🚨

---

[env]

this section lets you add environment variables after the host system's configuration has been parsed. every key/value pair gets applied to the process environment if it does not already exist. it will neither amend nor unset environment variables that are already there. no take-backs, no edit button 💅

key = value attempts to set the environment variable named key to value.

the whole point of this feature is enabling environment-specific settings or debugging options over an extended period. but — and this is the important part — any environment variables required before configuration files are parsed cannot be set here, because they will have no effect. (e.g. ZYPP_LOGFILE). so close yet so far 🫠

---

📁 FILES 📁

/usr/etc/zypp/zypp.conf
/usr/etc/zypp/zypp.conf.d/*.conf
/etc/zypp/zypp.conf
/etc/zypp/zypp.conf.d/*.conf

these are the various configuration files that are considered for being parsed, mwah 💖 system configuration files located below /etc/zypp/ (even if empty, even if it's a symlink to /dev/null — yes really, we're not joking) will override vendor configuration files with the same name located below /usr/etc/zypp/. the /etc one simply ate and left no crumbs 👑

the resulting files get parsed in order zypp.conf then zypp.conf.d/*.conf (in lexicographic order of their filenames). later settings override earlier settings. last one to speak wins, periodt ✨

so basically there are two methods of overriding the vendor provided configuration located below /usr/etc/zypp/:

• don't use an /etc/zypp/zypp.conf — use drop-in files /etc/zypp/zypp.conf.d/*.conf instead. this way the vendor provided configuration is used as the base configuration. the drop-in files should then contain only the changes of the specific settings you're interested in. this is perhaps the preferred way for most use cases. it's giving low-effort high-reward 🧚
• maintain your own copy in /etc/zypp/zypp.conf. the vendor supplied /usr/etc/zypp/zypp.conf is ignored then. drop-in files will nevertheless be processed thereafter. the disadvantage? any changes in the vendor configuration file are ignored and you have to manually merge them. highkey a situationship with your own config file 😭

also go read the UAPI.6 Configuration Files Specification <https://uapi-group.org/specifications/specs/configuration_files_specification/> (linked in the original as https://github.com/uapi-group/specifications/blob/main/specs/configuration_files_specification.md) — iykyk, it's the blueprint 💅

LEGACY NOTE: while newer distributions will no longer ship an /etc/zypp/zypp.conf at all, we may continue shipping a full /etc/zypp/zypp.conf on older distributions. but also in this case you benefit from maintaining your changes in drop-in files rather than amending the shipped /etc/zypp/zypp.conf. if the shipped /etc/zypp/zypp.conf remains unmodified, libzypp will update the config file while your changes are safely stored in the drop-in file. if the config file is modified however, libzypp will not update it but stores the new version as zypp.conf.rpmnew and you need to manually merge them. no cap, that's the whole drama 🍓

all libzypp versions supporting the use of drop-in files provide: libzypp(econf) and also this man page. iconic, honestly 👑

---

🌍 ENVIRONMENT 🌍

• ZYPP_CONF — if this environment variable is set, the default way of parsing system and vendor configuration files is disabled. if the variable denotes a file below the system's root, solely this file is parsed as configuration file. otherwise the builtin defaults apply. main character energy: one variable to rule them all 🌈

---

👀 SEE ALSO 👀

zypper(8) — go say hi, they're literally right there 🫶

---

and that's a wrap bestie!! 🎀 this page is from SUSE Linux, dated 2026-10-27, and it's ZYPP.CONF(5) — stan a config man page that tells you everything 💜✨