Raspberry Pi OS has a proxy menu of its own, inside raspi-config. It does not reach everything, and it writes your password in a way that breaks on some characters. This page shows what the menu really does, then each place that still needs attention: SSH, sudo, Chromium on the desktop, and Raspberry Pi Imager on the computer that writes the card.
We did not run a Raspberry Pi for this page. Every statement comes from the source code that ships today, read on 4 October 2026: raspi-config on its trixie branch (the current Raspberry Pi OS; the bookworm branch has the same proxy code), Raspberry Pi's documentation source, Raspberry Pi Imager 2.0.11.1, Debian's login and sudo files, and Chromium's and Qt's documentation.
| Where you set it | What it reaches | What it leaves out |
|---|---|---|
| raspi-config, A3 Network Proxy Settings | Logins (SSH, console), programs started from them, apt with or without sudo | Other commands under sudo, terminals already open |
export in a terminal | Programs started in that terminal | sudo, other terminals, the next login |
--proxy-server on Chromium | That Chromium window | Everything else |
| The proxy setting of your PC or Mac | Raspberry Pi Imager on that computer | The Pi itself |
/etc/profile.d/proxy.sh
SSH and console logins
Debian's /etc/profile reads every file in /etc/profile.d
curl, wget, git, pip
started from such a login
Chromium
started from such a terminal: it reads the variables
/etc/apt/apt.conf.d/01proxy
apt and apt-get
with or without sudo
Not: other commands under sudo
sudo resets the environment
What you need before you start
One proxy line, four parts
198.51.100.7Host:8080Port:hp_ir4k2Username:9fa2c1Password198.51.100.7:8080:hp_ir4k2:9fa2c1hp_ir4k2:9fa2c1@198.51.100.7:8080http://hp_ir4k2:9fa2c1@198.51.100.7:8080
raspi-config takes all four in one address: http://user:pass@host:port. Values shown are examples.
- A proxy address as
host:port, plus a user name and password if the proxy needs a login. If your provider sent the parts in another order, the proxy format guide sorts them out. - A user that can run sudo. The first user Raspberry Pi OS creates can.
- For a first test, any HTTP entry from our free proxy list will do. Free entries come and go, so test one first; the check further down shows how.
- Our free proxy setup generator turns your line into the Linux lines further down, with the password encoded where it has to be.
Step 1: set the proxy in raspi-config
- Open a terminal, or log in over SSH, and run
sudo raspi-config. - Choose 6 Advanced Options, then A3 Network Proxy Settings (1).
- Choose P1 All to use one proxy for HTTP, HTTPS, FTP and rsync. Enter it as
http://198.51.100.7:8080, or with a login ashttp://hp_ir4k2:9fa2c1@198.51.100.7:8080, and select OK. - Choose P6 Exceptions (2) and enter only the list, separated by commas:
localhost,127.0.0.1,.local. Select OK. - Select Finish, and reboot when raspi-config asks.
P2 to P5 set one scheme each, if HTTPS has to go to a different proxy than HTTP. P1 writes the same address for all four.
Step 2: what raspi-config wrote
raspi-config does not keep a setting of its own. It writes two ordinary files, and knowing them answers most questions later:
cat /etc/profile.d/proxy.sh
cat /etc/apt/apt.conf.d/01proxy
After P1 and P6 as above, they read:
export HTTP_PROXY="http://198.51.100.7:8080"
export http_proxy="http://198.51.100.7:8080"
export HTTPS_PROXY="http://198.51.100.7:8080"
export https_proxy="http://198.51.100.7:8080"
export FTP_PROXY="http://198.51.100.7:8080"
export ftp_proxy="http://198.51.100.7:8080"
export RSYNC_PROXY="http://198.51.100.7:8080"
export NO_PROXY="localhost,127.0.0.1,.local"
export no_proxy="localhost,127.0.0.1,.local"
Acquire::http::Proxy "http://198.51.100.7:8080";
Acquire::https::Proxy "http://198.51.100.7:8080";
The first file is read at login: Debian's /etc/profile loads every file in /etc/profile.d, which is why raspi-config asks for a reboot and why terminals that were already open do not change. The second is apt's own setting, so sudo apt update uses the proxy whatever the environment says.
Over SSH: raspi-config without the menu
On a headless Pi the same settings take one command each. raspi-config's nonint mode calls the function behind the menu directly:
sudo raspi-config nonint do_proxy all "http://198.51.100.7:8080"
sudo raspi-config nonint do_proxy no "localhost,127.0.0.1,.local"
Log out and back in, or reboot, so the next login reads the file. The same command fits a first-boot script for many Pis.
A password with special characters
raspi-config writes the address exactly as you type it, between double quotes, into a file the shell reads at every login. Inside double quotes the shell treats some characters as code, so a password containing them is changed or cuts the line short:
| In the password | What goes wrong | Write it as |
|---|---|---|
$ | The shell reads the rest as a variable name | %24 |
| a backquote | The shell runs what follows as a command | %60 |
\ | Before $, a backquote, " or another \ it escapes that character and disappears | %5C |
" | It ends the value | %22 |
@ | curl stops with Unsupported proxy syntax: the @ before the host has to be the only one | %40 |
curl and apt decode the percent forms back into the real characters (apt's address parser decodes the user name and password), so the proxy receives the password you were given. The proxy format guide has the full list.
sudo: apt works, other commands do not
Debian's sudoers starts every sudo command with a clean environment (Defaults env_reset). apt is not affected, because it reads 01proxy. Anything else under sudo, such as sudo curl or sudo pip, starts without the proxy.
For one command, keep the variables with -E:
sudo -E curl -s https://www.cloudflare.com/cdn-cgi/trace
To keep them for every sudo command, Debian's own sudoers already carries the right line, switched off. Put it into a file of its own with sudo visudo -f /etc/sudoers.d/proxy:
Defaults:%sudo env_keep += "http_proxy https_proxy ftp_proxy all_proxy no_proxy"
Chromium on the desktop
Chromium on Linux follows the GNOME or KDE proxy settings when it runs in one of those desktops. The Raspberry Pi desktop is neither, so Chromium takes its proxy from environment variables or from a flag. Two ways work:
chromium --proxy-server="http://198.51.100.7:8080"
or open a terminal after logging in again (so it carries the variables from Step 2) and start chromium from there. Close every Chromium window first: a running Chromium opens a new window in the same session and ignores the flag. The command is chromium; chromium-browser, which older answers use, is now an empty package that points to it.
Chromium never takes a login from the proxy setting: when the proxy asks for one, it shows a sign-in window. For a SOCKS5 proxy write socks5://198.51.100.7:1080; Chromium supports no login for SOCKS5 at all. The Chrome proxy guide covers the flag in full.
Raspberry Pi Imager behind a proxy
Imager runs on the computer that writes the card, not on the Pi, and it has no proxy setting of its own. When it fetches the list of images, it asks that computer's operating system once and downloads through the answer:
| Imager runs on | Where it finds the proxy | A proxy login |
|---|---|---|
| Windows | The proxy in Windows' settings | Not carried: Windows' setting has no login field |
| macOS | The Mac's network proxy settings | Carried only if the system setting hands one over |
| Linux | The http_proxy variable | Carried, as http://user:pass@host:port |
On Linux, start Imager from a terminal that has the variable: http_proxy="http://198.51.100.7:8080" rpi-imager. For a SOCKS5 proxy Imager asks the proxy to look up the names (socks5h). If your Windows proxy needs a login, the guide to proxy logins without a password field shows the two ways round it: an address allowlist or a small relay on 127.0.0.1.
Imager's settings for the card itself (hostname, Wi-Fi, SSH, user) have no proxy entry, so set the Pi's proxy after its first boot, with Step 1 or the SSH commands above.
Check that it worked
Log in again (or reboot), then:
env | grep -i _proxy
apt-config dump | grep -i proxy
curl -s https://www.cloudflare.com/cdn-cgi/trace | grep ^ip=
The first shows the variables from proxy.sh, the second apt's setting from 01proxy, the third the address the internet sees, which should be the proxy's. On Raspberry Pi OS Lite, install curl with sudo apt install curl first if it is missing; that also proves apt reaches the internet. Our IP lookup tells you who owns the address you see.
Mistakes other guides make
These come up in the pages and answers that rank for Raspberry Pi proxy searches:
- "P5 Exceptions". Raspberry Pi's own documentation names the exceptions entry P5. In the current raspi-config, P5 is RSYNC and P6 is Exceptions.
- Typing
no_proxy="localhost,127.0.0.1"into the exceptions box. The documentation shows that line, with curly quotes. raspi-config stores whatever you type as the value, so only the bare list belongs in the box. chromium-browser. That name is a leftover; the command ischromium.- Only an
apt.conf.dfile and/etc/environmentby hand. It works for apt, but on a Pi raspi-config already writes both kinds of file, so hand-made copies are one more place to change when the proxy does. - Proxy lines in
/etc/network/interfaces. That file configures network interfaces; logins and browsers do not take proxy settings from it.
Turning it off again
- In raspi-config: 6 Advanced Options, A3 Network Proxy Settings, P1 All, delete the address and select OK; the same in P6 Exceptions. raspi-config removes the lines from both files. Reboot.
- Over SSH:
sudo raspi-config nonint do_proxy all ""andsudo raspi-config nonint do_proxy no "", then log in again. - Remove
/etc/sudoers.d/proxywithsudo rm /etc/sudoers.d/proxyif you made it. - For Chromium started with the flag, close it and start it normally.
How we wrote this
We did not run a Raspberry Pi for this page. We read raspi-config's source on its trixie and bookworm branches (the proxy code is the same in both; the trixie branch last changed on 3 October 2026), the proxy section of Raspberry Pi's documentation source, the package list of Raspberry Pi's own archive, Raspberry Pi Imager 2.0.11.1's download code, Qt's documentation of how it finds the system proxy, Chromium's Linux proxy documentation, Debian's /etc/profile (base-files 13.8+deb13u7) and sudoers, and Linux-PAM's pam_env. The picture above is our own terminal reading of those sources on 4 October 2026.
Real problems come from Raspberry Pi Stack Exchange (the command-line question with 59,450 views, the Chromium question with 21,848) and the Raspberry Pi Forums.
Limits: no command on this page ran on a Pi. Whether the desktop session the Pi's login screen starts reads /etc/profile.d was not checked, which is why the Chromium section starts it from a terminal or with the flag.
Sources
All read on 4 October 2026.
- raspi-config, branches trixie and bookworm (github.com/RPi-Distro/raspi-config).
- Raspberry Pi documentation, "Configure your Raspberry Pi to use a proxy server" (github.com/raspberrypi/documentation).
- Raspberry Pi archive, trixie arm64 package list: chromium and chromium-browser (archive.raspberrypi.com).
- Raspberry Pi Imager 2.0.11.1,
src/curlnetworkconfig.cpp(github.com/raspberrypi/rpi-imager). - Qt 6, QNetworkProxyFactory::systemProxyForQuery (doc.qt.io).
- Chromium, Linux Proxy Config (chromium.googlesource.com).
- Debian base-files 13.8+deb13u7,
/etc/profile(sources.debian.org); Debian 13 sudoers. - Linux-PAM,
modules/pam_env/pam_env.c(github.com/linux-pam). - Raspberry Pi Stack Exchange questions 68580, 59292, 74264 and 24731; Raspberry Pi Forums topics 18634 and 28835.
- Our terminal reading of raspi-config and the documentation, 4 October 2026.
