How to Set Up a Proxy for YUM and DNF Repositories

When a RHEL-family host sits behind a corporate HTTP proxy, dnf install and yum update fail unless the package manager knows how to reach CDN and mirror URLs through that proxy. The durable fix is proxy= in /etc/dnf/dnf.conf or in an individual file under /etc/yum.repos.d/.

This guide documents the official settings for YUM on RHEL 7, DNF 4 on RHEL 8 through 10, and DNF 5 on recent Fedora releases. I verified config file paths on RHEL 10.2; I did not have a proxy endpoint in the lab, so the proxy examples follow Red Hat and upstream DNF documentation rather than live proxy traffic.

Where YUM and DNF read proxy settings

Package managers on the RHEL family stack configuration in layers:

On RHEL 8 and later, /etc/yum.conf is usually a symlink to /etc/dnf/dnf.conf. Confirm on your host before you edit:

readlink -f /etc/yum.conf

/etc/dnf/dnf.conf

That path is what DNF 4 reads on RHEL 10. DNF 5 on Fedora uses the same file according to upstream documentation.

RHEL 7 still runs YUM 3 with a standalone /etc/yum.conf (no symlink). The proxy, proxy_username, and proxy_password keys work the same way in the [main] section.

Check whether a proxy is already configured

Before you add settings, see whether proxy= is already present globally or in a repo file:

sudo grep -E '^(proxy|proxy_username|proxy_password|proxy_auth_method)=' /etc/dnf/dnf.conf /etc/yum.repos.d/*.repo 2>/dev/null

On a host with no proxy configured, that command prints nothing and exits with status 1. An empty result means DNF may still use http_proxy from the environment if those variables are exported.

Set a global proxy in dnf.conf

Add proxy= under [main] in /etc/dnf/dnf.conf (or /etc/yum.conf on RHEL 7) when every repository should use the same HTTP proxy. The value is a full URL with scheme and port:

[main]
gpgcheck=1
installonly_limit=3
proxy=http://proxy.example.com:3128

Use https:// in proxy= only when the proxy service itself listens with TLS. For most corporate HTTP proxies that tunnel HTTPS with CONNECT, http://proxy.example.com:3128 is correct even when repositories use https:// URLs.

After you save the file, refresh metadata to confirm DNF can reach repositories through the proxy:

sudo dnf clean all && sudo dnf makecache

When the proxy and credentials are correct, makecache completes without connection errors. Authentication failures often show 407 Proxy Authentication Required in the DNF error text.

Configure an authenticated proxy

DNF supports separate username and password keys instead of embedding credentials in the URL. That layout matches dnf.conf(5) and dnf5.conf(5):

[main]
proxy=http://proxy.example.com:3128
proxy_username=proxyuser
proxy_password=secret
proxy_auth_method=any

proxy_auth_method controls the proxy authentication mechanism; common values include basic, digest, ntlm, negotiate, and any. Check the DNF version's configuration reference for the complete supported list. If the password contains @, #, or other reserved characters, prefer proxy_password= over a URL-encoded proxy= line — see proxy URLs with special characters.

You can still use a single URL when your site documents that pattern:

proxy=http://proxyuser:secret@proxy.example.com:3128

Proxy passwords stored in dnf.conf are plain text. If the file contains credentials, ensure its permissions match your site's access requirements. Prefer keeping proxy_username and proxy_password in dnf.conf rather than in shell profiles when the proxy applies system-wide.

Set proxy for one repository only

To proxy only one .repo file — for example an internal mirror while public repos stay direct — add proxy= inside that repository section:

[internal-baseos]
name=Internal BaseOS mirror
baseurl=https://mirror.internal.example/rhel/$releasever/BaseOS/$basearch/os/
enabled=1
gpgcheck=1
proxy=http://proxy.example.com:3128
proxy_username=proxyuser
proxy_password=secret

Repository-level proxy= overrides the global value from [main] for that repo ID only. Other repos keep the global proxy or fall back to environment variables when no proxy is set.

List repo files before you edit so you match the correct section name:

ls -1 /etc/yum.repos.d/

epel.repo
epel-testing.repo
redhat.repo

The section name in brackets — for example [epel] — is the repo ID DNF uses in error messages.

Disable inherited proxy for one repository (proxy=_none_)

When [main] sets a global proxy but one repository should not use that value, disable inheritance in that repo section:

[internal-builds]
name=Internal build repository
baseurl=http://repo.internal.example/rpms/
enabled=1
gpgcheck=1
proxy=_none_

_none_ is a backward-compatible alias for an empty proxy= value. Both stop DNF from using the proxy inherited from [main] for that repository. However, if http_proxy or https_proxy environment variables are set, DNF may still route that repo through a proxy — unset or bypass those variables when the internal mirror must be reached directly.

DNF 4, DNF 5, and legacy YUM

The proxy keys are the same across the three package-manager generations:

DNF 4 and DNF 5 both document proxy_sslverify, proxy_sslcacert, and related TLS options for proxies that use HTTPS or client certificates. Set those only when your security team requires custom CA or client cert material for the proxy itself.

Subscription Manager proxy is separate

On registered RHEL systems, subscription-manager register and subscription-manager repos use /etc/rhsm/rhsm.conf, not dnf.conf. If registration fails with proxy errors while dnf makecache works (or the reverse), check both files.

Configure RHSM proxy under [server] in rhsm.conf, or with subscription-manager config --server.proxy_hostname=…. Full steps are in Register RHEL with Subscription Manager.

Environment variables as a fallback

When no explicit proxy= value applies, DNF can use curl proxy environment variables such as http_proxy and https_proxy. That fallback is separate from a repo-level proxy=_none_ override — see the section on disabling inherited proxy above when a repository must skip both the global proxy and exported variables.

For permanent, system-wide proxy settings that many tools share, environment variables may still be the right choice — see http_proxy and https_proxy in Linux. When you set proxy= in dnf.conf, DNF uses that value for repository traffic regardless of exported variables.

Troubleshooting

References

• DNF 4 configuration reference — proxy options
• DNF 5 configuration reference — dnf.conf
• yum.conf(5) — Red Hat Enterprise Linux 7
• curl environment variables — fallback when proxy= is unset

Summary

Corporate networks often require an HTTP proxy before any host can download RPM metadata or packages. On RHEL-family systems you configure that path in /etc/dnf/dnf.conf for DNF 4 and DNF 5, or in /etc/yum.conf on RHEL 7, using proxy= plus optional proxy_username, proxy_password, and proxy_auth_method. The same keys work in individual files under /etc/yum.repos.d/ when only some repositories need the proxy, and proxy=_none_ stops a repo from inheriting the global proxy.

The main pitfall is treating Subscription Manager and DNF as one configuration. Registration traffic reads rhsm.conf; package downloads read dnf.conf. Configure both on registered RHEL systems when both paths go through the proxy. When proxy= is absent, DNF falls back to curl environment variables — convenient for interactive shells, but dnf.conf is clearer for production servers and cron jobs.

After you change proxy settings, run dnf clean all and dnf makecache to confirm metadata downloads succeed. If authentication or TLS errors persist, verify credentials with your proxy team or adjust proxy_auth_method using your DNF version's configuration reference.