How to configure a proxy for npm, pip, apt, Docker, and git: a step-by-step guide to each tool's config
Table of contents
- Introduction: why package managers need their own proxy settings
- Preparation
- Basic concepts: why environment variables aren't enough
- Step 1: verify the proxy and prepare a reference string
- Step 2: configure npm via the .npmrc file
- Step 3: configure pip via pip.conf
- Step 4: configure apt via the apt.conf.d directory
- Step 5: configure docker at two levels
- Step 6: configure git via git config
- Verifying the result: a summary checklist
- Common mistakes and solutions
- Additional capabilities
- Faq: common proxy setup questions
- Conclusion
Introduction: why package managers need their own proxy settings
You've probably run into this situation before: your terminal has http_proxy and https_proxy exported, curl happily downloads pages, but npm install hangs for a minute and fails with an ETIMEDOUT error. Or apt update quietly tries to reach the mirror directly, as if no proxy exists at all. Or Docker can't pull the base layer when building an image, even though docker pull works from the same console. This isn't a bug or some mystery. Each tool just reads network settings in its own way, and environment variables only cover part of it.
This guide is specifically about the config files of five tools that no developer can do without: npm (.npmrc file), pip (pip.conf or pip.ini), apt (apt.conf.d directory), Docker (daemon.json and config.json), and git (git config). We're deliberately not repeating the material about environment variables in the terminal and CI. The task here is different: to show how to set up a proxy so that it always applies, no matter who runs the command or from where.
As a result, you'll have five working configs you can copy to any machine, an understanding of where each tool looks for settings, and a set of commands to verify everything. Plus you'll know how to quickly roll it all back.
Who this guide is for
- Developers whose work laptop or server sits behind a corporate or home proxy.
- Testers and automation specialists who need builds to go through a dedicated proxy address.
- Admins setting up standard workstation images.
- Anyone using a rented proxy (including mobile) for development and wanting a specific tool — not the whole system — to go through it.
What you need to know beforehand
Basic terminal skills are enough: open a console, navigate to a directory, edit a text file. We'll use nano on Linux and Notepad on Windows, but any editor will do. Understanding what an IP address and port are will also come in handy, though we'll cover the basics in the concepts section.
How long it'll take
If you configure all five tools in a row, plan for 60 to 90 minutes. Each individual tool takes 10–15 minutes including verification. The longest stage is Docker, because there are two levels of settings and a service restart is required.
Preparation
Before editing configs, let's gather everything you need. Skipping this step is the main reason people then spend hours guessing where the error is.
Required proxy details
You need four parameters. Write them down in a text file so you don't have to dig through messages:
- Proxy type: HTTP or HTTPS (sometimes SOCKS5, but most package managers expect an HTTP proxy).
- Address: a domain name or IP, for example proxy.corp.local or 10.20.30.40.
- Port: most often 3128, 8080, or 8888.
- Username and password, if the proxy requires authentication. Watch out for special characters in the password: they'll need encoding, which we'll cover below.
System requirements and versions
This guide has been tested on current 2026 versions and works for:
- Ubuntu 22.04 and 24.04, Debian 12 and 13 (for apt).
- Node.js 20 and 22 with npm 10 and 11.
- Python 3.10 and newer with pip 24 and newer.
- Docker Engine 25 and newer (the proxies key in daemon.json appeared in version 23; on older versions use a systemd drop-in, we'll show both options).
- Git 2.40 and newer.
If you're on Windows, all commands for npm, pip, and git work in PowerShell without changes; only the file paths differ. For Docker Desktop, proxy settings are configured through the graphical interface, which we'll also cover.
Access rights
For npm, pip, and git, regular user rights are enough: their configs live in the home directory. For apt and Docker you'll need sudo, because the files are in /etc and change the behavior of system services.
Backups
Before you start, copy the existing configs. One command per file, and you can always return to the original state:
cp ~/.npmrc ~/.npmrc.bak 2>/dev/null; cp ~/.config/pip/pip.conf ~/pip.conf.bak 2>/dev/null; cp ~/.gitconfig ~/.gitconfig.bak 2>/dev/null; sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak 2>/dev/null; sudo cp -r /etc/apt/apt.conf.d /etc/apt/apt.conf.d.bak 2>/dev/nullThe 2>/dev/null tail is needed so the command doesn't complain if the file doesn't exist yet. That's normal: many users don't have .npmrc or pip.conf initially.
Tip: create a proxy-configs folder in your home directory and keep reference versions of all five configs there. Moving to a new machine becomes copying five files.
Basic concepts: why environment variables aren't enough
Let's understand what's happening under the hood, otherwise the steps below will look like a set of magic spells.
What a proxy means in the context of a package manager
A proxy server is an intermediary. Instead of connecting directly to registry.npmjs.org, your npm connects to the proxy and asks it to go to registry.npmjs.org. For HTTPS resources, the CONNECT method is used: the proxy establishes a tunnel and encrypted traffic passes through it without decryption. The package manager needs to know the proxy address, port, and credentials if required.
How tools find out about a proxy
There are three layers of settings, and they stack into a priority chain:
- Command-line flags: for example, pip install --proxy. Valid for a single run.
- The tool's own config: .npmrc, pip.conf, and others. Always valid for that tool.
- Environment variables: http_proxy, https_proxy, no_proxy. Valid for all programs in the current session that read them.
The key phrase is that read them. And that's where the problems begin.
Four reasons why environment variables aren't enough
Reason one: user switching. When you run sudo apt update, the command executes as root, and sudo clears the environment by default (the env_reset option). Your http_proxy stays with the regular user. Moreover, apt itself downloads files under the service user _apt, which doesn't have your session at all.
Reason two: daemons and services. Docker Engine is a background service started by systemd at boot. It has never seen your terminal. The docker pull command only sends a request to the daemon, and the daemon downloads the image. That's why variables in your console have no effect on docker pull at all.
Reason three: different interpretations. Some programs read only lowercase http_proxy, others only HTTP_PROXY, others both. Old versions of npm ignored no_proxy. Some tools don't understand credentials in a variable. Your own config eliminates the guesswork.
Reason four: granularity. An environment variable is either set or not. But you might need to route only github.com through the proxy, not your internal GitLab. Or go to the public PyPI through the proxy, but to the internal index directly. Only configs can handle such rules: git supports setting a proxy for a specific URL, apt for a specific host, Docker for a list of exceptions at the daemon level.
Encoding special characters in a password
Username and password in configs are passed inside a URL of the form http://user:password@host:port. The characters @, :, /, #, ?, % and space inside the password break the address parsing. They need to be replaced with percent codes: @ becomes %40, : becomes %3A, # becomes %23, / becomes %2F, % becomes %25, space becomes %20. For example, the password p@ss:1 is written in the config as p%40ss%3A1. Remember this rule, it'll save you across all five tools.
Step 1: Verify the proxy and prepare a reference string
Goal of this stage: make sure the proxy actually works and get one verified connection string that we'll paste into all configs.
- Open a terminal. On Linux it's Ctrl+Alt+T, on Windows it's PowerShell from the Start menu.
- Assemble the connection string using the template http://LOGIN:PASSWORD@ADDRESS:PORT. Without authentication — just http://ADDRESS:PORT. Example: http://dev:s3cret@10.20.30.40:3128.
- Run a test request through curl, explicitly specifying the proxy with the -x flag so you don't depend on variables:
curl -x http://dev:s3cret@10.20.30.40:3128 -I https://registry.npmjs.org/ - Wait for the response. It should start with HTTP/2 200 or HTTP/1.1 200 OK. If you see 407 Proxy Authentication Required — wrong login or password. If Could not resolve proxy — typo in the address. If connection refused — wrong port or the proxy is down.
- Repeat the check for the other targets: https://pypi.org/simple/, https://deb.debian.org/, https://registry-1.docker.io/v2/, https://github.com/. For Docker, a 401 response is normal — it means you reached the registry and it's asking for a token.
- Write the final string to your text file. This is your reference proxy string.
Warning: if your password contains special characters, encode them at this step and test the encoded version via curl. Then in all subsequent configs you'll be pasting an already-proven working string.
Tip: if your provider gives you not one proxy but a pool of addresses or a mobile proxy with IP rotation, there's usually a single entry point: one host and port behind which IPs change automatically. Put this entry point in your configs, not specific IPs from the pool, otherwise the settings will become outdated the moment rotation happens.
Check: curl with the -x flag returns code 200 (or 401 for Docker Hub) for all five addresses. If even one doesn't respond, don't move on: configs won't fix a broken proxy.
Step 2: Configure npm via the .npmrc file
Goal of this stage: make npm install, npm view, and npm publish work through the proxy from any project and any console, including development environments that launch npm themselves.
Where the npm config lives
npm reads settings from several files in increasing priority: built-in values, the global file in the npm installation directory, the user-level ~/.npmrc (on Windows — C:\Users\NAME\.npmrc), and the project-level .npmrc in the project root next to package.json. For proxies, the user-level file is almost always used: it applies to all projects but doesn't end up in the repository.
Step-by-step setup
- Set the proxy for regular HTTP traffic:
npm config set proxy http://dev:s3cret@10.20.30.40:3128 - Set the proxy for HTTPS traffic (the npm registry works over HTTPS, so this setting is the main one):
Note that the value starts with http://, not https://. This is the address of the proxy itself, and it usually accepts connections over plain HTTP even when tunneling HTTPS.npm config set https-proxy http://dev:s3cret@10.20.30.40:3128 - If you have an internal registry or mirror that should be accessed directly, add exceptions separated by commas:
A dot before the domain means all subdomains.npm config set noproxy localhost,127.0.0.1,.corp.local - Open the file and make sure the lines were written:
On Windows: type $env:USERPROFILE\.npmrc. You should see three lines in key=value format.cat ~/.npmrc - If your corporate proxy substitutes certificates, add the company's root certificate:
Don't disable certificate verification via strict-ssl=false unless absolutely necessary: it opens the door to package substitution.npm config set cafile /etc/ssl/certs/corp-root.pem
The alternative path is to create the file manually. The contents of ~/.npmrc would be:
proxy=http://dev:s3cret@10.20.30.40:3128 https-proxy=http://dev:s3cret@10.20.30.40:3128 noproxy=localhost,127.0.0.1,.corp.localEach pair must be on its own line. No quotes or spaces around the equals sign.
What about yarn and pnpm
Yarn Classic (1.x) reads the same ~/.npmrc and additionally its own ~/.yarnrc with the proxy and https-proxy keys. Yarn Berry (2+) stores settings in .yarnrc.yml: keys httpProxy and httpsProxy. pnpm is fully compatible with .npmrc, no additional action needed. It's also worth remembering that npm ci and corporate IDEs launch npm under the same user, so the user-level .npmrc covers them too.
Tip: the command npm config list --json will show the final configuration taking all files into account. If you see proxy=null, the file wasn't read: check that it's in the home directory of the exact user you're running npm as.
Check: run npm view lodash version. After 1–3 seconds it should return a string with the version number. For clarity, you can temporarily unset the environment variables (unset http_proxy https_proxy) and repeat: npm should still work because it reads .npmrc.
Possible problems
- ETIMEDOUT or ECONNRESET: wrong proxy address or port, or the proxy blocks CONNECT to port 443. Verify the reference string via curl.
- 407 Proxy Authentication Required: an error in the login or password, most often an unencoded special character.
- UNABLE_TO_GET_ISSUER_CERT_LOCALLY: the proxy substitutes a certificate; you need a cafile with the corporate root certificate.
Step 3: Configure pip via pip.conf
Goal of this stage: make pip install and pip download work through the proxy, including inside virtual environments and when launched from Python scripts.
Where to find pip.conf
pip uses three levels of files: global (system-wide), user-level, and virtual environment level. The paths depend on the system:
- Linux, user-level: ~/.config/pip/pip.conf (the legacy path ~/.pip/pip.conf is also read).
- Linux, global: /etc/pip.conf.
- macOS, user-level: ~/Library/Application Support/pip/pip.conf, or if that folder doesn't exist — ~/.config/pip/pip.conf.
- Windows, user-level: %APPDATA%\pip\pip.ini, i.e. C:\Users\NAME\AppData\Roaming\pip\pip.ini.
- Inside a virtual environment: the pip.conf (or pip.ini) file right in the root of the venv directory.
To avoid guessing, ask pip itself: the command pip config debug will print all the paths it checks and mark the ones that exist.
Step-by-step setup
- Make sure pip is current: pip --version. You should have version 24 or newer.
- Set the proxy with a single command; pip will create the file in the right place:
Here global means the [global] section in the file, not the system level. The file created is user-level.pip config set global.proxy http://dev:s3cret@10.20.30.40:3128 - If the proxy substitutes certificates, specify the root certificate:
pip config set global.cert /etc/ssl/certs/corp-root.pem - See what you got:
Expected output: global.proxy='http://dev:s3cret@10.20.30.40:3128'.pip config list - Open the file and check the format. It should look like this:
Each on its own line, with the section in square brackets at the top.[global] proxy = http://dev:s3cret@10.20.30.40:3128 cert = /etc/ssl/certs/corp-root.pem
An important difference between pip and npm: pip doesn't have a separate setting for the HTTPS proxy. A single proxy key is used for all connections. And pip has no direct equivalent of noproxy in the config: it only takes exceptions from the no_proxy environment variable. If you need to reach an internal index directly, it's easier to specify a separate index-url for it and run pip with the --proxy flag set to an empty value for that case, or use a project-level pip.conf inside the venv without the proxy line.
Tip: if you have several projects and one needs a proxy while another doesn't, put pip.conf in the root of the corresponding virtual environment. venv settings take priority over user-level ones, and you get different behavior without switching global files.
Warning: don't add trusted-host = pypi.org to silence certificate errors. It disables authenticity verification and lets any intermediary slip you a fake package. The correct solution is the cert key with the corporate certificate.
Check: run pip download requests --no-deps -d /tmp/piptest. After a few seconds a requests-*.whl file will appear in the directory. Then delete the test directory. If you want to confirm that the config is what's working, unset the environment variables and repeat.
Possible problems
- ProxyError or Cannot connect to proxy: a typo in the address or wrong port. Compare with the reference string.
- Tunnel connection failed: 407: authentication error. Check the password encoding.
- SSLError CERTIFICATE_VERIFY_FAILED: you need the cert key with the proxy's root certificate.
- The file was written but pip doesn't see it: you're running pip from a different interpreter (e.g., python3 -m pip from another Python). Run pip config debug with the exact command you're using to install packages.
Step 4: Configure apt via the apt.conf.d directory
Goal of this stage: sudo apt update and sudo apt install download packages through the proxy, while requests to the internal mirror go directly.
Why apt.conf.d specifically
apt reads settings from /etc/apt/apt.conf and all files in the /etc/apt/apt.conf.d/ directory in alphabetical order. Good practice is not to touch other people's files but to create your own with a numeric prefix. The number sets the reading order: a file 80proxy will apply after 01autoremove and other system files. This is where settings survive any apt package updates.
Step-by-step setup
- Create a new settings file:
An empty editor will open.sudo nano /etc/apt/apt.conf.d/80proxy - Enter two lines for HTTP and HTTPS repositories. Note the quotes and semicolons — in apt syntax they're mandatory:
Acquire::http::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::https::Proxy "http://dev:s3cret@10.20.30.40:3128"; - If there's an internal mirror that shouldn't use the proxy, add a line with an exception. The word DIRECT in capitals means a direct connection:
Acquire::http::Proxy::mirror.corp.local "DIRECT"; - Save the file: in nano press Ctrl+O, then Enter, then Ctrl+X to exit.
- Restrict permissions on the file, since it contains a password:
Only root can read the contents.sudo chmod 600 /etc/apt/apt.conf.d/80proxy - Check that apt parsed the file without syntax errors:
You should see the lines Acquire::http::Proxy and Acquire::https::Proxy with your values.apt-config dump | grep -i proxy
Here's a full example file for clarity:
Acquire::http::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::https::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::http::Proxy::mirror.corp.local "DIRECT"; Acquire::https::Proxy::mirror.corp.local "DIRECT";A one-off alternative without a file: sudo apt -o Acquire::http::Proxy="http://10.20.30.40:3128" update. The -o flag is handy for testing a value before writing it to the config.
Tip: proxy servers that cache deb packages themselves often have a separate port for apt. Ask your administrator: if there is one, apt update will speed up several times thanks to the local cache.
Check: run sudo apt update. The output will show Hit or Get lines with repository addresses and no Err lines. Note that we haven't set any environment variables, and sudo would reset them anyway, yet apt still got onto the network. That's the effect of a proper config.
Possible problems
- Err: 407 Proxy Authentication Required: authentication failed, check the special character encoding.
- Could not connect or Connection timed out: apt went directly. Most likely there's a typo in the file that apt-config dump doesn't show. Check the case in Acquire and the double colons.
- E: Syntax error: missing semicolon or quote at the end of a line.
- The file is in place but the DIRECT exception doesn't work: make sure the hostname in the exception line matches the one in sources.list exactly, without http:// and without the port.
Step 5: Configure Docker at two levels
Goal of this stage: docker pull, docker build, and docker compose pull download images through the proxy, and containers get proxy settings automatically when needed.
Two levels that are often confused
Docker has two independent places where the proxy is needed in different ways:
- Daemon level (the dockerd service). It's the one that downloads images from the registry. Configured in /etc/docker/daemon.json or via systemd. Requires a service restart.
- Client level (the ~/.docker/config.json file). It doesn't affect image downloads. But it automatically passes proxy variables into launched containers and into the build process, so that apt or pip inside the container also sees the proxy.
Configure only the client — docker pull won't work. Configure only the daemon — images download, but RUN apt-get update inside your Dockerfile fails. You need both.
Part A: daemon via daemon.json
- Check the version: docker version. If the server version is 23.0 or newer, use daemon.json. If older, skip to Part B.
- Open the daemon settings file:
If the file already exists and contains other keys, add the proxies block inside the same curly braces with a comma. If the file doesn't exist, create it from scratch.sudo nano /etc/docker/daemon.json - Enter the settings block:
Note: the keys are written with hyphens and in lowercase exactly like this. This is the daemon's format; the client's keys will be different.{ "proxies": { "http-proxy": "http://dev:s3cret@10.20.30.40:3128", "https-proxy": "http://dev:s3cret@10.20.30.40:3128", "no-proxy": "localhost,127.0.0.0/8,registry.corp.local" } } - Save the file (Ctrl+O, Enter, Ctrl+X).
- Verify that the JSON is valid, otherwise the daemon won't start:
If the command printed the file contents with indentation, the syntax is correct. If it complains about Expecting value or Extra data, look for an extra or missing comma.python3 -m json.tool /etc/docker/daemon.json - Restart the service:
The restart will take 5–15 seconds. All running containers will stop, so do this at a quiet moment.sudo systemctl restart docker - Verify that the daemon came up: sudo systemctl status docker. You should see active (running) in green.
Warning: one extra comma in daemon.json and Docker won't start at all, taking down all containers on the machine with it. Always validate the file with json.tool before restarting and keep a backup nearby.
Part B: daemon via systemd (for older versions and as an alternative)
- Create a directory for additional service settings: sudo mkdir -p /etc/systemd/system/docker.service.d
- Create a file: sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf
- Enter:
[Service] Environment="HTTP_PROXY=http://dev:s3cret@10.20.30.40:3128" Environment="HTTPS_PROXY=http://dev:s3cret@10.20.30.40:3128" Environment="NO_PROXY=localhost,127.0.0.0/8,registry.corp.local" - Save and apply: sudo systemctl daemon-reload, then sudo systemctl restart docker.
Yes, environment variables are used here, but they're set not in your console but in the service definition: the daemon receives them at startup from systemd. This is the only way for Docker older than version 23. If you have both daemon.json and a systemd file configured, daemon.json takes priority.
Part C: client via ~/.docker/config.json
- Open or create the file nano ~/.docker/config.json. If the file already contains an auths block with your registry logins, don't delete it — add a new block next to it with a comma.
- Enter:
Here the keys are camelCase: httpProxy, httpsProxy, noProxy. This differs from daemon.json, and you shouldn't confuse them.{ "proxies": { "default": { "httpProxy": "http://dev:s3cret@10.20.30.40:3128", "httpsProxy": "http://dev:s3cret@10.20.30.40:3128", "noProxy": "localhost,127.0.0.0/8,.corp.local" } } } - Save the file. No restart is required; the client reads it on every command.
Now when you run docker run and docker build, the container will automatically receive the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY variables (in both cases). That means apt-get and pip inside your Dockerfile will also go through the proxy without manual ARG and ENV.
Docker Desktop on Windows and macOS
Open the settings via the tray icon, go to Resources, then Proxies. Switch to Manual proxy configuration, enter the address in the Web Server (HTTP) and Secure Web Server (HTTPS) fields, and the exception list in Bypass proxy settings for these hosts and domains. Click Apply and restart. The client config.json on Windows is located at C:\Users\NAME\.docker\config.json and is configured just as described above.
Tip: the docker info command prints a section with HTTP Proxy, HTTPS Proxy, and No Proxy. This is the fastest way to find out whether the daemon picked up your settings without triggering a download.
Check: run docker pull hello-world. The image weighs a few kilobytes and downloads in a couple of seconds, at the end you'll see Status: Downloaded newer image. Then check the client part: docker run --rm alpine env | grep -i proxy. The output should contain HTTP_PROXY and HTTPS_PROXY lines with your address.
Possible problems
- Docker doesn't start after editing daemon.json: syntax error. Check sudo journalctl -u docker -n 30, it will point to the offending line. Restore from the backup.
- docker pull hangs and times out even though docker info shows the proxy: the daemon wasn't restarted after the edit, or the proxy doesn't allow CONNECT to registry-1.docker.io. Verify the reference string via curl.
- Inside a build, apt-get update fails while docker pull works: the client config.json isn't configured, or the build is going through a remote builder that reads a different file.
- The container got the proxy but can't reach a neighboring container: add internal service names and the Docker subnet to noProxy.
Step 6: Configure git via git config
Goal of this stage: git clone, fetch, pull, and push over HTTPS go through the proxy, while direct access can be left for the internal server and a separate proxy can be set for a specific host.
Where git stores settings
Three levels: system (/etc/gitconfig), user-global (~/.gitconfig, on Windows — C:\Users\NAME\.gitconfig), and local within a repository (.git/config). The proxy is usually set globally, and fine-grained exceptions — also globally but bound to a URL.
Step-by-step setup
- Set the proxy for all HTTPS and HTTP connections with one command:
Unlike npm, git has no separate https.proxy for the HTTPS protocol: the http.proxy key applies to both. The https.proxy setting appears in old guides, but it's not a standard git key and is ignored.git config --global http.proxy http://dev:s3cret@10.20.30.40:3128 - If you don't need the proxy for an internal server, set an empty value for its URL specifically:
An empty string means a direct connection. The part between http. and .proxy is the URL prefix the rule applies to.git config --global http.https://git.corp.local.proxy "" - If you need a different proxy for a specific host (say, a dedicated mobile one), specify it the same way with the URL binding:
git config --global http.https://github.com.proxy http://dev:s3cret@10.20.30.41:3128 - If the proxy substitutes certificates, add the root certificate:
git config --global http.sslCAInfo /etc/ssl/certs/corp-root.pem - Check the resulting file:
You'll see the lines http.proxy=... and http.https://git.corp.local.proxy= with an empty value.git config --global --list | grep -i proxy
After these commands, the ~/.gitconfig file will look like this:
[http] proxy = http://dev:s3cret@10.20.30.40:3128 sslCAInfo = /etc/ssl/certs/corp-root.pem [http "https://git.corp.local"] proxy = [http "https://github.com"] proxy = http://dev:s3cret@10.20.30.41:3128This kind of granularity isn't achievable through environment variables: no_proxy can only exclude hosts, not assign different proxies to different servers.
What about SSH addresses
The http.proxy setting doesn't affect addresses like git@github.com:user/repo.git, because that's the SSH protocol, not HTTP. If your proxy allows tunneling to port 22 via CONNECT, you can configure the SSH client in the ~/.ssh/config file with the ProxyCommand directive and the nc or corkscrew utility. But many corporate proxies forbid such connections. The simplest and most predictable path is to switch remote addresses to HTTPS: git remote set-url origin https://github.com/user/repo.git and use an access token instead of a password.
Tip: to avoid storing the proxy password in ~/.gitconfig in plain text, you can move it to a separate file with 600 permissions and include it via the include directive. Create ~/.gitconfig-proxy with an [http] section, and add [include] path = ~/.gitconfig-proxy to the main file. The main config can then be safely shown to colleagues.
Check: run git ls-remote https://github.com/git/git.git HEAD. After a couple of seconds, a line with the commit hash and the word HEAD will return. The command doesn't create files or clone anything, making it the perfect test for the network layer. Then verify the exception: git ls-remote to the internal server should work even with the proxy unreachable.
Possible problems
- Failed to connect to proxy or Could not resolve proxy: a typo in the address.
- Received HTTP code 407 from proxy after CONNECT: authentication error, check the password encoding.
- SSL certificate problem: unable to get local issuer certificate: you need http.sslCAInfo. Don't use http.sslVerify false on a permanent basis.
- The URL rule doesn't apply: the prefix must match the beginning of the address in the remote. If the remote is written as https://www.github.com, the rule for https://github.com won't trigger.
Verifying the result: a summary checklist
Once you've configured all five tools, run the final check. It's deliberately designed to eliminate the influence of environment variables and confirm that the configs themselves are working.
- Open a new terminal and unset the variables if they're set: unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY no_proxy NO_PROXY. In PowerShell: Remove-Item Env:HTTP_PROXY and similarly for the others.
- Check npm: npm view express version. A version number is expected.
- Check pip: pip download six --no-deps -d /tmp/t. A downloaded whl file is expected.
- Check apt: sudo apt update. Hit or Get lines with no Err are expected.
- Check Docker: docker pull hello-world and docker run --rm alpine env | grep -i proxy. A downloaded image and the variables inside the container are expected.
- Check git: git ls-remote https://github.com/git/git.git HEAD. A commit hash is expected.
Success indicators
- All six commands completed without environment variables in the console.
- The files .npmrc, pip.conf, 80proxy, daemon.json, config.json, and .gitconfig all contain the same reference proxy string.
- Files with passwords (80proxy, daemon.json, .npmrc, pip.conf, .gitconfig) have 600 permissions or are accessible only to root.
- Exceptions for internal hosts work: requests to them succeed even with the proxy off.
- Backups of the original files sit nearby and you know how to restore them.
Check: if even one item isn't satisfied, go back to the section for the corresponding tool and compare your file with the example from this guide character by character. Nine times out of ten the cause is a typo or an unencoded character in the password.
Common mistakes and solutions
Mistake 1: error 407 Proxy Authentication Required everywhere
Cause: the password contains a special character (@, :, #, %) that wasn't encoded, and the tool parsed the address incorrectly.
Solution: encode the characters with percent codes (@ to %40, : to %3A, # to %23, % to %25) and test the new string via curl -x before writing it to the configs.
Mistake 2: works from the terminal, doesn't work via sudo
Cause: sudo resets the environment, and you haven't created a config yet. A classic for apt.
Solution: create /etc/apt/apt.conf.d/80proxy as in Step 4. For other tools under root, remember that root reads its own home directory /root, not yours: if you need npm or pip as root, the config must be in /root/.npmrc or /root/.config/pip/pip.conf.
Mistake 3: Docker won't start after editing daemon.json
Cause: invalid JSON — an extra comma after the last element, a missing brace, single quotes instead of double.
Solution: run sudo journalctl -u docker -n 30, find the error line, fix the file, and validate it with python3 -m json.tool before the next restart. In the worst case, restore daemon.json.bak.
Mistake 4: docker pull works but apt-get inside a Dockerfile fails
Cause: the daemon is configured but not the client. Processes inside the container don't inherit the daemon's settings.
Solution: create ~/.docker/config.json with the proxies.default block as in Part C of Step 5. After that, docker build automatically passes the variables to RUN stages.
Mistake 5: SSL certificate errors in all tools
Cause: the proxy performs traffic inspection and injects its own certificate, which the system doesn't trust.
Solution: get the proxy's root certificate in PEM format from your administrator and specify it: npm cafile, pip cert, git http.sslCAInfo. For apt and Docker, it's enough to add the certificate to the system trust store: copy it to /usr/local/share/ca-certificates/ and run sudo update-ca-certificates, then restart Docker. Don't disable certificate verification with strict-ssl, trusted-host, and sslVerify flags.
Mistake 6: pip ignores pip.conf
Cause: multiple Python versions on the machine, and you're editing the config for one while running another. Or the file is in an obsolete location that this particular version doesn't read.
Solution: run python3 -m pip config debug with the same command you use to install packages. The output will show which files were found. Move the settings to the user-level path that was found.
Mistake 7: git goes through the proxy even to the internal server
Cause: the exception rule is set for a URL that doesn't match the address in the remote. Or it's set in the local .git/config of another repository.
Solution: check the exact address with git remote -v, copy its beginning up to the hostname, and set the rule http.EXACT_URL.proxy with an empty value via --global.
Mistake 8: everything worked, then broke after a proxy password change
Cause: the password is hardcoded in five different files, and you didn't update all of them.
Solution: use the command grep -rl 'old_password' ~/.npmrc ~/.config/pip ~/.gitconfig ~/.docker and sudo grep -rl for /etc/apt/apt.conf.d and /etc/docker to find all occurrences and update each one. Then run the summary checklist.
Additional capabilities
Local proxy aggregator as a single entry point
If your proxy credentials change frequently or the address pool rotates, it's convenient to run a lightweight local proxy on your machine (say, 127.0.0.1:3128) that already knows where to go and with what credentials. Then a single address without a password goes into all five configs, and changing credentials happens in one place. This also solves the problem of tools that handle URL authentication poorly.
Mirrors and caching proxies for packages
A proxy doesn't have to be universal. For apt there are caching proxies that store deb files locally and serve them to the whole office. For npm and pip, corporations set up private registries that proxy the public ones and cache them as well. In that case, instead of the proxy key, you use registry in .npmrc and index-url in pip.conf, and the proxy for the outside world is configured on that registry. For Docker, the registry-mirrors key in daemon.json plays a similar role.
Separate settings for different projects
A project-level .npmrc next to package.json, pip.conf inside a venv, and a local .git/config let one project go through the proxy while another goes directly. Just don't commit files with passwords to the repository: add them to .gitignore or use substitution variables like ${PROXY_URL}, which npm can expand from the environment when reading .npmrc.
Deployment automation
All five configs are plain text files. They're easy to roll out with a script or a configuration management system: the script receives the reference string as a single parameter and generates files in the right formats. For post-deployment verification, use the commands from the summary checklist: they don't require interactivity and are suitable for automated tests.
Password storage security
The minimum is 600 permissions on every file with a password. Better — move secrets to separate included files (include in git, a separate file in apt.conf.d for the authorization lines only). Even better — a proxy without password authentication but with IP restrictions or a local aggregator as described above. And never send configs with passwords into chats and tickets in full.
FAQ: common proxy setup questions
Should I remove the http_proxy variables from .bashrc now
Not necessarily. Tool configs take priority over variables, so there's no conflict. But if you want only package managers to go through the proxy while the browser and other programs go directly, removing the variables is better: they affect everything.
Why is the https-proxy for npm written with http://, not https://
Because this is the address of the proxy server itself, not the protocol of the target resource. Most proxies accept connections over plain HTTP and tunnel HTTPS inside. If your proxy really accepts TLS connections, then write https://, but that's rare.
Can I use a SOCKS5 proxy
npm — no, it only supports HTTP proxies. pip — yes, with the pysocks package installed and an address of the form socks5://host:port. git — yes, format socks5h://host:port, where the letter h means name resolution on the proxy side. apt — only via additional transports, not by default. Docker — no. In practice, it's easier to get an HTTP port from your provider.
How to quickly disable the proxy in all tools
npm: npm config delete proxy and npm config delete https-proxy. pip: pip config unset global.proxy. git: git config --global --unset http.proxy. apt: delete or rename /etc/apt/apt.conf.d/80proxy. Docker: remove the proxies block from daemon.json and config.json, restart the service. Or just restore the .bak files from your backups.
Where to store configs on Windows
npm: C:\Users\NAME\.npmrc. pip: C:\Users\NAME\AppData\Roaming\pip\pip.ini. git: C:\Users\NAME\.gitconfig. Docker: C:\Users\NAME\.docker\config.json for the client and Docker Desktop settings for the daemon. apt isn't used on Windows, except in WSL, where Linux paths inside the subsystem apply.
Does this work inside WSL
Yes, WSL is regular Linux, all configs live at Linux paths inside the distribution. Note that Docker Desktop with WSL integration uses the daemon on the Windows side, so daemon settings are made in Docker Desktop, and the client config.json is inside WSL in the home directory.
How do I find out which file each tool read
npm config list --json, pip config debug, apt-config dump, docker info, git config --show-origin --list. Each command shows not only the values but also the source they came from. This is the first thing to run when debugging.
Why doesn't Docker Compose see the proxy
Compose is a client; it uses the same daemon and the same ~/.docker/config.json. If docker pull works but docker compose pull doesn't, check that you're running compose as the same user and that the compose file doesn't override container environment variables that mask the proxy.
Can I set different proxies for npm and pip
Yes, that's the advantage of having your own configs. Each file is independent. For example, npm can go through one proxy while pip goes through another with a different IP and geolocation if the task requires it.
Conclusion
Let's sum up. You verified the proxy via curl and got a reference connection string with a correctly encoded password. Then you put it in five places: ~/.npmrc for npm, pip.conf for pip, /etc/apt/apt.conf.d/80proxy for apt, daemon.json and ~/.docker/config.json for Docker, and ~/.gitconfig for git. For each tool you set exceptions for internal hosts where supported and confirmed that everything works even with a completely clean environment. That's what distinguishes your own configs from environment variables: they don't depend on who ran the command, from where, or through which service.
What to do next. Save the five reference files in a personal folder and write a short script that deploys them to a new machine. Check permissions on files containing passwords. If you have colleagues with the same problem, share the summary checklist with them: it saves hours of debugging.
Where to go next. The next level is caching proxies and private registries for packages, a local proxy aggregator as a single entry point, and automated network settings checks in pipelines. And if you need to set up a proxy not for tools but for a specific terminal session or CI job, there's a separate guide on environment variables for that. Now you know exactly where its capabilities end and the capabilities of configs begin.