Using pip install Behind a Proxy, From One Command to a Saved Config
By the ProxyV4 Engineering Team · Updated:
To run pip install through a proxy, pass it on the command line: pip install --proxy http://USER:PASS@IP:PORT requests. To make it permanent, save the same URL as proxy under [global] in pip.conf (pip.ini on Windows) or export HTTPS_PROXY. This guide covers where those files live on each OS, how to encode awkward passwords, why SOCKS needs an extra package, and the equivalent settings for conda and uv.
The quick fix: pip install --proxy
The --proxy option takes a URL in the form scheme://[user:passwd@]proxy.server:port. It applies to that one invocation only, which makes it the safest way to confirm a proxy works before you save it anywhere.
python -m pip install --proxy http://USER:[email protected]:PORT requestsCalling pip as python -m pip makes sure you are configuring the pip that belongs to the interpreter you care about, which avoids a whole class of "it worked in one terminal but not the other" confusion when several Pythons are installed.
Use http:// as the scheme even though PyPI is served over HTTPS. The scheme describes how pip talks to the proxy; the HTTPS session to PyPI is tunnelled through it with CONNECT and stays encrypted end to end.
Make it permanent with a pip.conf proxy entry
pip reads INI-style config files at three levels: global (whole machine), user, and site (inside the active virtual environment). Later levels override earlier ones, and PIP_CONFIG_FILE points to an extra file loaded last.
[global]
proxy = http://USER:[email protected]:PORTFile locations by operating system
These are the locations the pip documentation lists for current releases. Legacy paths such as ~/.pip/pip.conf are still read if they exist.
- Linux user:
~/.config/pip/pip.conf(followsXDG_CONFIG_HOME). Global:/etc/pip.confor/etc/xdg/pip/pip.conf. - macOS user:
~/Library/Application Support/pip/pip.confif that folder exists, otherwise~/.config/pip/pip.conf. Global:/Library/Application Support/pip/pip.conf. - Windows user:
%APPDATA%\pip\pip.ini. Global:C:\ProgramData\pip\pip.ini. - Virtual environment (any OS):
pip.conforpip.iniin the environment's root folder.
Let pip write the file for you
Rather than guessing the path, let pip create the file and report what it loaded. pip config debug lists every file it checks and whether each exists.
python -m pip config --user set global.proxy http://USER:[email protected]:PORT
python -m pip config list
python -m pip config debugUse --site instead of --user to scope the proxy to one virtual environment, which suits a project that needs the proxy while the rest of the machine does not.
Environment variables pip honors
Every pip option can be set as PIP_<OPTION>, so PIP_PROXY is equivalent to --proxy. Independently of that, pip's HTTP stack reads the standard HTTPS_PROXY, HTTP_PROXY and NO_PROXY variables when no proxy option is given. Command-line flags beat PIP_* variables, which beat config files.
# Linux and macOS, current shell only
export HTTPS_PROXY=http://USER:[email protected]:PORT
export NO_PROXY=localhost,127.0.0.1,.internal.example.com# Windows PowerShell, current session only
$env:HTTPS_PROXY = "http://USER:[email protected]:PORT"
python -m pip install requestsOn Windows the system proxy you set in Settings does not automatically reach pip; Python tools read environment variables or their own config. The Windows proxy setup guide explains how the system setting, per-app settings and user environment variables relate, so you can decide where the value should live. When a stale variable is the problem, clear it for one run (env -u HTTPS_PROXY -u HTTP_PROXY pip install ... on Linux and macOS, or Remove-Item Env:HTTPS_PROXY in the current PowerShell session) and pass --proxy explicitly.
pip proxy authentication with special characters
Proxy passwords are often random strings, and some characters break the URL. Pip parses the proxy as a URL, so a raw @ makes it read the rest of the password as the host name, and a # cuts the URL off entirely. Percent-encode the user name and password before inserting them.
python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1], safe=''))" 'p@ss:w#rd'
# p%40ss%3Aw%23rdThen write http://USER:p%40ss%3Aw%[email protected]:PORT. In an INI file, also watch for % itself: pip's config parser reads values literally, so the encoded string can be pasted as is. In a Windows batch file, though, % has to be doubled.
Avoid committing a pip.conf that contains credentials to a repository. For shared build machines, inject PIP_PROXY from the CI system's secret store at job time.
SOCKS5 proxies and pip
pip can use socks5:// and socks5h:// proxy URLs, but its networking layer needs the PySocks package for that, and pip does not bundle it. Without it you get Missing dependencies for SOCKS support.
That creates a chicken-and-egg problem when the proxy is the only way out: you cannot download PySocks through a proxy you cannot yet use. Either install it from a wheel copied in by other means, or simply use the proxy's HTTP mode for pip. Most providers offer both protocols, and for package downloads HTTP CONNECT is the simpler path. The HTTP vs SOCKS5 comparison covers when the difference matters.
Does a dedicated IP make sense for package installs?
For public PyPI, any working proxy will do; PyPI does not care where you download from. A dedicated IP earns its keep in narrower cases: a private package index or artifact server that only accepts connections from known addresses, a build server whose outbound traffic must leave from one approved IP, or a test environment that has to download from a specific country.
ProxyV4 private datacenter IPv4 fits those jobs. Each IP has one tenant for the whole term and keeps the same address while active, so you can add it to a server's firewall once. Every proxy supports HTTP(S) and SOCKS5 with username and password, both on one port if you choose, which sidesteps the PySocks issue. Traffic is unmetered, so large wheels and repeated CI installs do not run up a bill.
It is a poor fit if your company already runs a mandatory proxy; use that one. You can order a single IP, try a real pip install through it, and check live per-IP prices on the pricing page before scaling.
Conda, uv and Poetry behind a proxy
The rest of the Python toolchain mostly reads the same environment variables, but conda keeps its own setting.
conda proxy settings in .condarc
Conda stores proxies under proxy_servers in ~/.condarc. Set it with conda config so the YAML is written correctly.
conda config --set proxy_servers.http http://USER:[email protected]:PORT
conda config --set proxy_servers.https http://USER:[email protected]:PORT
conda config --show proxy_serversAs with pip, the https key usually still takes an http:// URL, and percent-encoding rules for the password are the same. When proxy_servers is not set, conda generally picks up HTTPS_PROXY from the environment instead.
uv and Poetry
uv has no proxy key of its own; it reads HTTPS_PROXY, HTTP_PROXY, ALL_PROXY and NO_PROXY. Poetry resolves and downloads through the same Python HTTP stack as pip, so exporting HTTPS_PROXY is the reliable approach for both. Neither reads pip.conf, so a proxy saved only there will not reach them.
Common pip proxy errors and what they mean
- `ProxyError('Cannot connect to proxy.')` with repeated
Retryingwarnings: wrong host or port, or a firewall blocking the proxy port. Test the line with the proxy checker first. - `Tunnel connection failed: 407 Proxy Authentication Required`: wrong credentials or an unencoded special character in the password.
- `SSLError` or `CERTIFICATE_VERIFY_FAILED`: usually a corporate proxy that inspects TLS. Point pip at the company CA with
--certrather than marking hosts as trusted; a plain forwarding proxy does not cause this. - Works in the shell, fails in an IDE or service: the IDE or service does not inherit your shell variables. Put the proxy in pip.conf or the service's environment.
Frequently asked questions
What is the format for pip install --proxy?
scheme://[user:passwd@]host:port, for example http://USER:[email protected]:PORT. Use http:// for an HTTP proxy even when installing from HTTPS indexes.
Where is pip.ini on Windows?
The per-user file is %APPDATA%\pip\pip.ini and the machine-wide file is C:\ProgramData\pip\pip.ini. Run python -m pip config debug to see every path pip checks.
Why does pip ignore my proxy inside a virtual environment?
It usually does not; a site-level pip.conf or a different interpreter is overriding it. python -m pip config list shows the effective values for the environment you are in.
Does pip support a SOCKS5 proxy?
Yes, if PySocks is installed in the same environment as pip. Otherwise use the proxy's HTTP mode, which needs no extra package.
Can I keep the same proxy IP for a firewall rule on my package server?
With a ProxyV4 private IPv4 proxy, yes. The IP stays the same while active, and renewing before expiry keeps it. A refund only applies to proxies that fail for a technical reason, as set out in the refund policy.
Give package installs one fixed egress IP
Order a private IPv4 with HTTP(S) and SOCKS5 on one port, username and password login and unmetered traffic. Start with a single IP and test your installs.
Order one IP