You run sudo dnf upgrade and the terminal hangs
The package manager stops at Downloading metadata, waits ten seconds, and prints a connection timeout. Your browser loads the Fedora website without issue. You check the network cable, the Wi-Fi icon, and the IP address. Everything looks normal. The network works, but the path is restricted. Your organization routes all traffic through a proxy server for caching, filtering, or logging. Fedora doesn't know about the proxy, so it tries to connect directly and fails.
You need to tell Fedora where to send the traffic. The complication is that Fedora doesn't use a single global switch for proxies. Different tools listen to different configuration sources. The desktop environment, the network manager, the package manager, and the shell environment all have their own knobs. If you only turn one knob, some tools will work and others will fail. The fix is to match the scope of the proxy configuration to the scope of the tools you need to route.
What's actually happening
A proxy server acts as an intermediary between your machine and the internet. Your system sends a request to the proxy, the proxy fetches the data, and returns it to you. This setup is common in enterprises and some home networks. Fedora respects the Linux convention where applications check multiple sources for proxy settings. Some tools read environment variables. Some read configuration files. Some query the desktop session bus. Some ignore everything and use hardcoded defaults.
Understanding the hierarchy prevents half-working configurations. If you set a proxy in the shell but not in DNF, curl works but dnf fails. If you set it in GNOME but not in /etc/environment, the browser works but a background script fails. The goal is to apply the proxy at the correct layer so every relevant tool picks it up without manual overrides.
Configure proxy for the current shell session
Use environment variables when you need a temporary proxy for a single terminal session or a quick test. This method affects the current shell and any child processes spawned from it. It does not persist across reboots and does not affect other users or services.
Here's how to set the standard proxy variables for the active session. Most CLI tools like curl, wget, and git check these variables automatically.
# Set HTTP proxy for the current shell session.
# Tools like curl and git read this variable automatically.
export http_proxy=http://proxy.example.com:8080
# Set HTTPS proxy. Many tools check this separately from http_proxy.
# Omitting this can cause mixed content failures for secure sites.
export https_proxy=http://proxy.example.com:8080
# Define hosts that should bypass the proxy.
# Localhost and loopback addresses must always be excluded.
# Including internal domains prevents routing local traffic through the proxy.
export no_proxy=localhost,127.0.0.1,::1,.local,.corp
Some tools are case-sensitive and require uppercase variables. If a tool fails to connect despite the lowercase variables being set, try exporting HTTP_PROXY and HTTPS_PROXY as well. This is a legacy quirk in older applications.
If the proxy requires authentication, you can embed credentials in the URL. Be aware that the command line appears in shell history and process listings. Use this method only on single-user machines or when testing. For production, prefer a configuration file or a credential helper.
Log out and back in to clear the variables. Environment variables don't retroactively apply to running processes.
Configure system-wide proxy for all users
Use /etc/environment when you want all users and all CLI tools to route through the proxy on every login. This file is read by PAM during the authentication process. It sets environment variables for every session, including SSH logins and graphical logins.
Here's how to append the proxy variables to the system-wide environment file. This change persists across reboots and applies to all users.
# Append proxy variables to the system-wide environment file.
# PAM reads this file during login, making variables available to all sessions.
# Use tee to write as root while preserving file permissions.
sudo tee -a /etc/environment <<'EOF'
http_proxy=http://proxy.example.com:8080
https_proxy=http://proxy.example.com:8080
no_proxy=localhost,127.0.0.1,::1,.local
EOF
The no_proxy variable is not optional. If you omit local addresses, tools will try to route traffic to localhost through the proxy. This breaks local database connections, Docker sockets, and internal API calls. Always include localhost,127.0.0.1,::1 and any internal domain suffixes.
Systemd services run in a clean environment. They do not inherit /etc/environment or shell exports. If a service needs a proxy, you must configure it explicitly in the unit file using Environment= or EnvironmentFile=. This isolation prevents service crashes from leaking credentials and keeps the service environment predictable. Configure services explicitly or they will fail silently.
Configure DNF proxy separately
Use /etc/dnf/dnf.conf when only the package manager needs a proxy, or when the proxy requires credentials you don't want in the global environment. DNF has its own configuration keys for proxy settings. If these keys are set, DNF ignores environment variables. This allows you to route package updates through a proxy while keeping the rest of the system direct.
Here's how to add proxy settings to the DNF configuration file. Edit the file in /etc/. Never edit files in /usr/lib/. Files in /usr/lib/ ship with packages and get overwritten on updates.
# Edit /etc/dnf/dnf.conf to route package manager traffic through a proxy.
# DNF ignores environment variables if these keys are set in the config file.
proxy=http://proxy.example.com:8080
# Uncomment and set these if the proxy requires authentication.
# Storing credentials in plain text is a security risk on shared machines.
# Consider using a proxy that supports anonymous access for package updates.
# proxy_username=your_user
# proxy_password=your_password
DNF reads its config on every invocation. No restart needed. If you see Error: Failed to download metadata for repo 'fedora': Cannot prepare internal mirrorlist: No URLs in mirrorlist, check the proxy URL syntax. A missing http:// prefix causes DNF to treat the proxy as a local path and fail immediately.
Configure NetworkManager and GNOME proxy
Use NetworkManager connection settings when the proxy depends on the active network connection, such as a corporate Wi-Fi profile. Use GNOME settings when you are configuring the desktop environment and need browser integration alongside system tools. NetworkManager and GNOME share proxy configuration. Changes in one propagate to the other.
Here's how to set proxy settings for a specific NetworkManager connection using nmcli. This persists across reboots and applies when the connection activates.
# Configure proxy settings for a specific NetworkManager connection.
# This persists across reboots and applies when the connection activates.
# Replace 'Wired connection 1' with your actual connection name.
nmcli connection modify 'Wired connection 1' \
proxy.method manual \
proxy.browser-only no \
proxy.http host proxy.example.com \
proxy.http port 8080
# Reload the connection to apply changes immediately without disconnecting.
# This triggers the desktop environment to update its proxy settings.
nmcli connection up 'Wired connection 1'
For desktop users, gsettings provides a direct way to configure the GNOME proxy. This affects GTK applications and the default browser integration.
# Set GNOME desktop proxy mode to manual.
# This affects GTK applications and the default browser integration.
gsettings set org.gnome.system.proxy mode 'manual'
# Define the HTTP proxy host for the desktop environment.
gsettings set org.gnome.system.proxy.http host 'proxy.example.com'
# Define the HTTP proxy port.
gsettings set org.gnome.system.proxy.http port 8080
# Define the HTTPS proxy host.
# Some tools check HTTPS separately even in the desktop environment.
gsettings set org.gnome.system.proxy.https host 'proxy.example.com'
# Define the HTTPS proxy port.
gsettings set org.gnome.system.proxy.https port 8080
GNOME settings propagate to NetworkManager. If you change one, the other follows. Verify the active connection name with nmcli connection show --active before modifying settings.
Verify the proxy configuration
Run these commands to confirm the proxy is active and routing traffic correctly. Check environment variables first, then test connectivity.
# Print the current proxy environment variables.
# If these are empty, your shell session is not using a proxy.
echo $http_proxy
echo $https_proxy
# Test connectivity through the proxy using curl.
# The -I flag fetches headers only, which is faster for verification.
# A successful response indicates the proxy is working for CLI tools.
curl -I https://fedoraproject.org
# Check DNF proxy configuration.
# This shows the effective proxy URL DNF will use for package operations.
dnf config-manager --show
If curl hangs, check the proxy URL syntax. A missing http:// prefix causes silent failures in some tools. If curl returns curl: (7) Failed to connect to proxy.example.com port 8080: Connection refused, the proxy server is unreachable or the port is wrong. Verify the proxy address and port with your network admin before blaming Fedora.
Common pitfalls and error patterns
Proxy configuration failures usually stem from scope mismatches or syntax errors. Watch for these patterns.
The no_proxy variable is missing local addresses. Tools try to route localhost traffic through the proxy and fail. You see errors like Connection refused when accessing local services. Add localhost,127.0.0.1,::1 to no_proxy.
DNF ignores environment variables because /etc/dnf/dnf.conf has a proxy= line. You set http_proxy but DNF still fails. Check the DNF config file. Remove the proxy= line or update it to match the environment.
Case sensitivity breaks older tools. You set http_proxy but wget fails. Some legacy tools only check HTTP_PROXY. Export both lowercase and uppercase versions.
Systemd services fail because they don't read /etc/environment. A service needs internet access but can't connect. Add Environment="http_proxy=..." to the service unit file and reload systemd.
Authentication credentials are exposed in shell history. You embedded username:password@ in the export command. The credentials appear in ~/.bash_history. Use a configuration file or a credential helper for production systems.
curl: (7) Failed to connect to proxy.example.com port 8080: Connection refused
This error means the proxy server is not responding. Check the proxy URL, port, and network connectivity. Verify the proxy is running and accepting connections on the specified port.
Verify the proxy address and port with your network admin before blaming Fedora.
When to use each method
Use shell environment variables when you need a temporary proxy for a single terminal session or a quick test. Use /etc/environment when you want all users and all CLI tools to route through the proxy on every login. Use /etc/dnf/dnf.conf when only the package manager needs a proxy, or when the proxy requires credentials you don't want in the global environment. Use NetworkManager connection settings when the proxy depends on the active network connection, such as a corporate Wi-Fi profile. Use GNOME settings when you are configuring the desktop environment and need browser integration alongside system tools. Stay on environment variables if you are managing a headless server and don't want desktop dependencies.