How To Setup APT Proxy on Debian 13

If you manage a Debian 13 server on a corporate network or a restricted environment, you already know the pain — apt update fails silently, packages refuse to download, and no error message tells you why. The root cause is almost always the same: APT does not automatically inherit system-wide proxy settings, even when http_proxy is set in your shell environment. You need to configure APT Proxy on Debian 13 explicitly, using APT’s own configuration system.

This guide gives you three working methods to configure an APT proxy on Debian 13 “Trixie” — from a simple one-file setup for a single machine, to a full caching proxy server with Apt-Cacher NG for managing multiple machines on a local network. You will also learn how to verify the configuration, bypass the proxy for specific hosts, and fix the most common errors sysadmins run into.

Debian 13 “Trixie” was officially released on August 9, 2025, and is currently at point release 13.4 as of March 14, 2026. It ships with APT 3.0, which introduces a new default dependency resolver called Solver3 and color-coded terminal output. Despite these improvements, proxy configuration in APT 3.0 still requires explicit setup — it is deliberate by design.

Whether you are a beginner who just installed Debian 13 for the first time or an intermediate sysadmin scripting deployments across a fleet of servers, this tutorial covers every scenario you need.

Prerequisites

• Operating System: Debian 13 “Trixie” (any point release, including 13.4)
• Access level: sudo privileges or a root shell
• Proxy server details: IP address and port of your proxy (example: 192.168.1.100:3128 for Squid, or 192.168.1.100:3142 for Apt-Cacher NG)
• Optional: Proxy username and password if your proxy requires authentication
• Tools: A terminal — either local or via SSH
• Text editor: nano, vim, or any editor you prefer

No additional packages are required for Methods 1 and 2. Method 3 (Apt-Cacher NG) requires a server machine on your local network with internet access.

What Is an APT Proxy and Why It Matters

An APT proxy is a middleman between your Debian system and the package repositories it downloads from. When you run apt install or apt update, APT normally connects directly to Debian mirrors. With a proxy configured, that traffic routes through the proxy server first.

There are two common reasons sysadmins set this up.

The first is corporate or restricted networks. Firewalls block direct internet access, and all outbound traffic must pass through an approved proxy. Without configuring APT to use that proxy, package management simply does not work.

The second is home labs and multi-machine deployments. If you manage three or more Debian machines, every apt install downloads the same packages repeatedly over your internet connection. A caching proxy like Apt-Cacher NG stores .deb packages locally after the first download. Every subsequent install on any machine pulls from the local cache, saving bandwidth and cutting install times significantly.

Why Environment Variables Are Not Enough

This is the most common mistake beginners make. You set http_proxy in /etc/environment or in your .bashrc, run sudo apt update, and nothing changes.

The reason is that APT is a non-interactive process. When it runs under sudo, it does not inherit the calling user’s environment variables by default. Even if you set the variable system-wide, APT ignores it unless you explicitly pass it through.

APT reads its proxy configuration exclusively from:

• /etc/apt/apt.conf
• Files inside /etc/apt/apt.conf.d/
• The -o flag passed directly to the apt command

Step 1: Update Your System Before Making Changes

Before modifying any configuration, update your package index to make sure your system is in a clean state. This also confirms whether APT currently has network access at all.

sudo apt update

If this command hangs or throws a connection error, your network either requires a proxy (which you are about to configure) or has a different connectivity issue worth investigating first.

Run this to check basic internet connectivity from your server:

curl -I https://deb.debian.org

If curl connects but apt does not, that confirms APT needs explicit proxy configuration and you are in the right place.

Step 2: Configure APT Proxy on Debian 13 Using a Dedicated Config File (Recommended)

This is the cleanest, most maintainable approach and the one recommended by the Debian community. It keeps proxy settings isolated in a single file that is easy to update or remove without touching any other APT configuration.

APT automatically reads every file inside /etc/apt/apt.conf.d/ in alphanumeric order. Creating a dedicated file there means your proxy config will not interfere with other APT settings.

Create the Proxy Configuration File

Create a new file named proxy.conf inside the apt.conf.d directory:

sudo nano /etc/apt/apt.conf.d/proxy.conf

The file is empty. You will add the proxy directives in the next step.

File naming note: APT reads files in this directory in alphanumeric order. If you want the proxy settings to load with a specific priority, prefix the filename with a number such as 95proxy.conf. For most setups, proxy.conf works fine.

Add Proxy Directives (No Authentication Required)

If your proxy does not require a username and password, add these two lines:

Acquire::http::Proxy "http://192.168.1.100:3128/";
Acquire::https::Proxy "http://192.168.1.100:3128/";

Replace 192.168.1.100 with your proxy server’s actual IP address or hostname, and 3128 with the correct port.

The Acquire::http::Proxy directive handles standard HTTP repository traffic. The Acquire::https::Proxy directive handles HTTPS-secured repository connections. Both lines are needed for full coverage.

Add Proxy Directives (Authentication Required)

If your proxy server requires a login, include the credentials directly in the URL:

Acquire::http::Proxy "http://username:password@192.168.1.100:3128/";
Acquire::https::Proxy "http://username:password@192.168.1.100:3128/";

Important: If your password contains special characters like @ or #, you must URL-encode them. For example, @ becomes %40 and # becomes %23. A password like P@ss#123 would be written as P%40ss%23123 inside the URL string.

Alternative Block Syntax

APT also accepts a compact block format that some sysadmins find easier to read and maintain:

Acquire {
  http::Proxy "http://192.168.1.100:3128/";
  https::Proxy "http://192.168.1.100:3128/";
}

Both formats work identically. Use whichever fits your team’s style.

Save the file with Ctrl+O, then press Enter, then exit with Ctrl+X if you are using nano.

Test the Configuration

No service restart is needed. APT reads the config file on every invocation. Run a test immediately:

sudo apt update

You should see APT fetching package indexes normally. To confirm the proxy is being used, check your proxy server’s access log while running the update. On a Squid proxy server, for example:

sudo tail -f /var/log/squid/access.log

You should see requests from your Debian 13 machine’s IP address flowing through.

Step 3: Set APT Proxy via Environment Variable (Temporary / Per-Session Method)

This method is useful when you need a proxy for a single command or a single session without changing any configuration file. It is ideal for troubleshooting a new proxy before committing it to a config file.

One-Command Inline Proxy

Pass the proxy inline, directly before the apt command:

sudo http_proxy="http://192.168.1.100:3128/" apt update

This sets the variable only for that specific command. Nothing is written to disk and nothing persists after the command finishes.

Export Proxy for the Full Session

If you need the proxy active for multiple commands in the same terminal session, export the variables:

export http_proxy="http://192.168.1.100:3128/"
export https_proxy="http://192.168.1.100:3128/"

Then run APT with the -E flag to preserve environment variables through sudo:

sudo -E apt install curl

The -E flag is critical here. Without it, sudo strips environment variables from the session before running the command. Your http_proxy export gets discarded, and APT connects without a proxy.

This method is not persistent. Variables disappear when the terminal session ends or when you close the SSH connection. Use Method 2 (the config file) for anything that needs to survive reboots.

Step 4: Pass a Proxy Directly to a Single APT Command

APT supports passing configuration options with the -o flag. This lets you specify a proxy for one command without touching any file and without environment variables:

sudo apt -o Acquire::http::Proxy="http://192.168.1.100:3128/" update

This approach is excellent for use in CI/CD pipelines, automation scripts, or Docker build steps where you want proxy behavior to be explicit and visible in the script itself.

If you have a proxy configured in apt.conf.d/proxy.conf, the -o flag overrides it for that specific command run. This means you can temporarily use a different proxy without editing any files.

Step 5: Setup a Caching APT Proxy with Apt-Cacher NG (Multi-Machine Networks)

If you manage multiple Debian 13 machines on the same local network, Apt-Cacher NG is worth setting up. It acts as a local package cache. The first machine to download a package stores it in the cache. Every other machine on the network pulls from that local cache instead of the internet, cutting download times and reducing bandwidth consumption significantly.

Apt-Cacher NG listens on port 3142 by default.

Install Apt-Cacher NG on the Server Machine

Run this on the machine that will act as the cache server (it needs direct internet access):

sudo apt update
sudo apt install apt-cacher-ng

Enable and Start the Service

sudo systemctl enable --now apt-cacher-ng

This command enables Apt-Cacher NG to start automatically at boot and also starts it immediately.

Confirm the service is running:

sudo systemctl status apt-cacher-ng

Expected output includes active (running) in green. With APT 3.0’s color output on Debian 13, you will notice status output is easier to read at a glance.

Confirm it is listening on port 3142:

ss -tlnp | grep 3142

Configure Each Client Machine

On every Debian 13 client that should use the cache, create the proxy config file pointing to your cache server’s IP:

echo 'Acquire::http::Proxy "http://SERVER_IP:3142";' | sudo tee /etc/apt/apt.conf.d/01proxy

Replace SERVER_IP with the actual LAN IP address of your Apt-Cacher NG server.

Verify the Cache Is Working

On the server, watch the Apt-Cacher NG log in real time:

sudo tail -f /var/log/apt-cacher-ng/apt-cacher-ng.log

On a client machine, run:

sudo apt update

You will see log entries on the server confirming the client’s request came through. On the second client to run the same update, cached packages will be served from disk at LAN speeds.

Step 6: Bypass the Proxy for Specific Hosts

In mixed environments, you may need APT to use the proxy for public Debian mirrors but connect directly to internal or private repositories. APT supports this with the DIRECT keyword.

Open your proxy config file:

sudo nano /etc/apt/apt.conf.d/proxy.conf

Add a host-specific exception alongside your global proxy directive:

Acquire::http::Proxy "http://192.168.1.100:3128/";
Acquire::https::Proxy "http://192.168.1.100:3128/";
Acquire::http::Proxy::repo.internal.lan "DIRECT";

The third line tells APT to connect directly to repo.internal.lan without going through the proxy. APT evaluates host-specific entries first before falling back to the global directive.

You can add as many DIRECT exceptions as you need, one line per host. This setup is especially useful in enterprise environments where private Debian mirrors live on the intranet.

Step 7: Verify Your Full APT Proxy Configuration

After any configuration change, use apt-config dump to confirm exactly what APT has loaded. This command reads all files in apt.conf.d and prints the merged result:

apt-config dump | grep -i proxy

Expected output when a proxy is configured:

Acquire::http::Proxy "http://192.168.1.100:3128/";
Acquire::https::Proxy "http://192.168.1.100:3128/";

If the output is empty, APT has no proxy configured. Check that your file is in the right directory and has correct syntax.

For deeper debugging, run APT in verbose mode to see exactly how it handles connections:

sudo apt -o Debug::Acquire::http=true update 2>&1 | head -60

This outputs low-level HTTP connection details including which proxy APT is attempting to use.

Remove or Disable the Proxy

To permanently remove the proxy:

sudo rm /etc/apt/apt.conf.d/proxy.conf

To temporarily disable it without deleting:

sudo mv /etc/apt/apt.conf.d/proxy.conf /etc/apt/apt.conf.d/proxy.conf.disabled

Confirm it is gone:

apt-config dump | grep -i proxy

No output confirms no proxy is active.

Troubleshooting Common APT Proxy Errors on Debian 13

Even with the right configuration, things can go wrong. Here are the five errors you are most likely to see and how to fix each one.

Error 1: Could not connect to proxy (111: Connection refused)

APT cannot reach the proxy server at the address you specified.

• Verify the proxy IP and port are correct
• Test connectivity with: nc -zv 192.168.1.100 3128
• Check that the proxy service is running on the server
• Check firewall rules — Debian 13 uses nftables as its default firewall backend, so verify port 3128 or 3142 is open

Error 2: 407 Proxy Authentication Required

The proxy requires credentials and either they are missing or wrong in your config.

• Open /etc/apt/apt.conf.d/proxy.conf and verify the username and password
• Check for special characters in the password that need URL encoding (@ = %40, # = %23)
• Confirm the proxy user account is active and not expired

Error 3: apt update Ignores Proxy When Using sudo

You exported http_proxy in your shell but APT still connects directly.

• This happens because sudo strips environment variables by default
• Use sudo -E apt update to preserve the environment, or use the apt.conf.d method which does not rely on environment variables at all

Error 4: Proxy Works for HTTP but Fails for HTTPS Repositories

APT fetches HTTP repositories normally but HTTPS sources like security.debian.org fail.

• Check your proxy.conf file — you likely have Acquire::http::Proxy but are missing Acquire::https::Proxy
• Add the HTTPS line and run apt-config dump | grep -i proxy to confirm both are loaded

Error 5: Apt-Cacher NG Does Not Cache HTTPS Repositories

Packages from HTTPS sources bypass the cache entirely.

• This is expected behavior. Apt-Cacher NG cannot inspect or cache encrypted HTTPS traffic by default
• For internal repositories, switch them to HTTP if possible within your LAN
• Alternatively, configure Apt-Cacher NG with SSL bumping, but this adds significant complexity and is outside the scope of a standard setup.