Configure Network Proxies in elementary OS
A proxy server sits between your computer and the wider internet, forwarding web requests through another machine or service. Schools, offices, libraries and some managed apartment or business networks use proxies to filter traffic, record access, cache content or provide controlled access to external websites. At home, most elementary OS users connected through an NBN modem or a Telstra, Optus or TPG router will not need one.
The setting can still be useful when you move between networks. A work laptop may need an authenticated HTTP proxy, a university connection may provide a proxy auto-configuration file, and a development environment may require proxy variables for package managers. If you are new to the distribution, this overview of elementary OS explained provides useful background before you adjust system-level networking.
What a Proxy Changes
A proxy is different from a normal router. Your router connects your device to the internet, while a proxy receives a request from an application and makes the external connection on the application’s behalf. The proxy then sends the response back to your computer. Depending on its design, it may handle ordinary web traffic, encrypted HTTPS connections, FTP, SOCKS traffic or several of these types.
A proxy can be manual or automatic. A manual configuration gives you a server address, port number and possibly a username and password. Automatic configuration normally uses a PAC file, which is a small JavaScript file containing rules that decide whether a particular address should go directly to the internet or through a proxy.
This distinction matters because a proxy is not the same thing as a VPN. A VPN usually creates a broader encrypted tunnel for the device or network, while a proxy often affects only applications that honour the desktop proxy configuration. Changing the proxy in System Settings will not automatically route every command-line tool, Flatpak or background service through it.
Do not enter a proxy address simply because a website or pop-up recommends one. An unknown proxy can inspect unencrypted requests, interfere with certificates and collect account details. Use the server name, port and bypass information supplied by your employer, school or network administrator, and remove the setting when you leave that network.
Locate the Network Controls
Open the Applications menu, launch System Settings and select Network. The exact appearance can vary between elementary OS releases, but the panel generally shows available Wi-Fi networks, wired connections, VPN profiles and related connection options. Connect to the intended network first so that you can confirm the settings against the correct interface.
For Wi-Fi, select the connected network and look for an options, details or configuration control. Wired connections usually appear separately when an Ethernet cable is plugged in. On a home network, the connection will normally use DHCP, which automatically obtains an IP address, gateway and DNS servers from your router. Proxy settings are separate from those values and should not be entered in the IP address or DNS fields.
Some versions of elementary OS present a dedicated proxy area under Network, while others expose fewer controls in the graphical panel. If you cannot see a proxy section, do not assume the feature is unavailable. The underlying desktop settings may still be accessible through the command line, and individual applications may have their own proxy preferences.
Record the original state before making changes. Note whether the proxy mode is disabled, automatic or manual, and copy the PAC address or bypass list into a secure note. This is especially useful on a shared household connection, where another person may need the normal direct connection after you finish using a corporate or campus network.
Enter a Manual Proxy
Choose the manual option only when your administrator has supplied a fixed proxy host and port. The host may be a fully qualified name such as proxy.example.com or an IP address such as 192.0.2.25. The port is commonly a four-digit value, but there is no universal standard. Enter the supplied value precisely rather than guessing from another device.
If the interface provides separate fields, enter HTTP and HTTPS details as instructed. Some organisations use the same proxy for both protocols; others use distinct endpoints. A SOCKS proxy is a different service and should be entered only in a SOCKS field. Do not paste http:// into a host field unless the interface specifically asks for a complete URL.
Look for a bypass or “ignore hosts” field. Local addresses such as localhost, 127.0.0.1 and ::1 should usually bypass the proxy. Your organisation may also provide internal domains, private address ranges or special names that must remain local. A typical bypass list might contain entries such as localhost, 127.0.0.1, *.internal.example, but the correct syntax depends on the settings panel and proxy service.
Proxy authentication deserves careful attention. If the proxy requires credentials, enter them only into a trusted system prompt or the approved application. Avoid placing a password directly in a shell command, browser profile or shared configuration file. Some systems ask for credentials on the first request and store them in the desktop keyring; check that the keyring is locked when you leave a shared computer.
Apply the change, close the panel and open a fresh browser window. Existing tabs may retain connections created before the new setting was saved. Visit an ordinary HTTPS website and then an address that should bypass the proxy, such as a local printer or internal service. A successful connection through one path does not prove that every application is using the same configuration.
Use Automatic Configuration Files
A PAC file is often the best choice for workplaces and campuses because its rules can select different routes for different destinations. Your network administrator may give you an address ending in .pac, or the address may be provided by an automatic discovery system. In System Settings, select the automatic configuration option and enter the complete PAC URL if a field is available.
A PAC file can direct local services straight to the destination while sending public websites through the organisation’s proxy. It may also choose different servers for different locations, which is useful for a university with several campuses. If the file cannot be downloaded, the desktop may appear offline even though the Wi-Fi connection itself is working.
Test automatic configuration on more than one type of address. Check an external site, an internal company or university page, and a local device if you have one. Australian university networks commonly use eduroam or institution-specific rules, so the correct proxy behaviour may depend on whether you are connected to campus Wi-Fi, home NBN or a mobile hotspot.
PAC files are scripts, so use only a trusted address supplied by the organisation managing the network. A malicious PAC file can redirect requests to an unwanted server or create confusing failures. When you stop using the managed network, switch the mode back to disabled or automatic discovery as directed by your administrator.
Cover Applications and Command-Line Tools
The desktop proxy setting is most reliable for applications that use the system’s GLib or GNOME network preferences. Many browsers and graphical utilities follow it, but some provide independent settings. Check the application’s own network page if a browser still reports a connection error after the system proxy has been configured.
Flatpak applications can have their own sandbox permissions and may not behave exactly like native applications. A sandboxed app might need permission to access the network, or it might ignore a setting that another program uses. Change the application’s own proxy preference first, and avoid granting broad filesystem or network permissions simply to force a proxy to work.
Command-line programs often rely on environment variables. For a temporary shell session, you can use values such as:
export http_proxy="http://proxy.example.com:8080"
export https_proxy="http://proxy.example.com:8080"
export no_proxy="localhost,127.0.0.1,::1"
Use the exact address and port provided by your administrator. The https_proxy value may still begin with http:// when an HTTP CONNECT proxy is used; the correct prefix describes the connection to the proxy, not necessarily the final website. Do not include a password in these variables because they can be exposed through shell history or process inspection.
Package tools may need separate configuration. APT can use proxy directives in a file under /etc/apt/apt.conf.d/, while Git, Snap and language package managers may have their own settings. A system administrator should make these changes on a managed machine. For personal use, a temporary environment variable is safer than leaving credentials in a permanent configuration file.
When working on a home project, remember that unrelated internet services may still depend on direct access. For example, researching a renovation and comparing practical pendant lighting options should not require a proxy unless the network specifically imposes one. This kind of simple external-site test can help distinguish a proxy problem from a site or DNS problem.
Test, Troubleshoot and Remove the Setting
Start troubleshooting by checking the basics: confirm that Wi-Fi or Ethernet is connected, verify the proxy hostname, and test the port with the network administrator’s approved method. A typo in the host name can look like a general internet outage. A blocked port can produce a timeout, while incorrect credentials normally produce an authentication error.
If websites load but software updates fail, the application probably does not read the desktop proxy setting. If only one browser fails, inspect that browser’s connection preferences. If internal pages work while public pages fail, the PAC rules, bypass list or authentication policy may be wrong. If public sites work but local devices disappear, the proxy may be handling local addresses that should have been excluded.
Certificate warnings require special care. Do not disable HTTPS verification to make a proxy work. A managed organisation may use its own certificate authority for traffic inspection, but that certificate should be installed only from an authorised support channel and with a clear explanation of its purpose. On a personal NBN connection, an unexpected certificate warning is a reason to stop and investigate.
The command line can reveal whether elementary OS has a desktop proxy value. These examples query common GNOME settings:
gsettings get org.gnome.system.proxy mode
gsettings get org.gnome.system.proxy.http host
gsettings get org.gnome.system.proxy.http port
A result such as 'none' means the desktop proxy mode is disabled. Values such as 'manual' or 'auto' indicate that a manual server or PAC configuration may be active. The exact keys can differ between releases, so treat these commands as inspection tools rather than a universal replacement for System Settings.
To restore a direct connection, return to the Network panel and select the disabled or direct option, clear any manual proxy fields and save the change. If you used shell variables, close that terminal or unset them with unset http_proxy https_proxy no_proxy. Recheck browser, update and local-network access afterwards, particularly if you have moved from a Sydney office or Melbourne campus back to your home network.
A proxy configuration should serve a specific network requirement, not remain enabled indefinitely. The most reliable routine is to identify the network, record its supplied settings, apply them in System Settings, test an external and local destination, and restore direct access when the managed connection is no longer in use. On elementary OS, that small checklist prevents many mysterious browser, update and printer failures.
