Using pip install Behind a Proxy, From One Command to a Saved Config

· 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.

Give package installs one fixed egress IP

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 requests

Calling 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]:PORT

File 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 (follows XDG_CONFIG_HOME). Global: /etc/pip.conf or /etc/xdg/pip/pip.conf.
  • macOS user: ~/Library/Application Support/pip/pip.conf if 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.conf or pip.ini in 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 debug

Use --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 requests

On 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%23rd

Then 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_servers

As 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 Retrying warnings: 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 --cert rather 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

Related articles

Proxy setup
Setting a Proxy on Windows 10 and Windows 11
Set an HTTP(S) proxy on Windows 10 or 11: the Proxy page in Settings, saving the login in Credential Manager, variables for CLI tools and netsh winhttp.
Proxy setup
Python requests through an authenticated proxy, step by step
Send Python requests through an authenticated HTTP(S) proxy: build the proxies dict, attach it to a Session, encode odd passwords, rotate a list, check the IP.
Knowledge base
HTTP or SOCKS5: Picking the Proxy Protocol Your Software Needs
HTTP vs SOCKS5 proxy in plain terms: what each protocol carries, why HTTPS works through both, where UDP matters, and how to test which one a server speaks.
Products
Dedicated datacenter proxies: one private IPv4 per customer
Private IPv4 proxies in the US, Vietnam, Japan, South Korea, Singapore, the UK and Hong Kong. One tenant per IP, HTTP(S) and SOCKS5, no traffic metering.
Proxy setup
Set up your proxy, tool by tool
Proxy setup instructions you can follow with the dashboard open: antidetect browsers, operating systems, browser extensions and scraping libraries, all with authenticated HTTP(S) or SOCKS5.
Knowledge base
Configuring npm, Yarn and pnpm to Install Packages Through a Proxy
npm config set proxy and https-proxy explained, plus Yarn classic, Yarn Berry and pnpm proxy keys, .npmrc precedence, SOCKS5 and safe settings for CI builds.
Knowledge base
Connecting to SSH Servers Through an Authenticated SOCKS5 Proxy
SSH through a SOCKS5 proxy with ProxyCommand and ncat, why OpenBSD nc -X 5 cannot log in, HTTP CONNECT tunnels, and how to keep the proxy password private.
Knowledge base
Setting Up proxychains-ng With an Authenticated SOCKS5 Proxy
Proxychains SOCKS5 with username and password: the ProxyList line, which proxychains4.conf is read, proxy_dns, chain types and fixing Go tools that bypass it.
Free tools
Check proxies in bulk: status, exit IP and latency
Free online proxy checker: paste up to 100 ip:port:user:pass lines and see which proxies work, their exit IP and latency, plus what each failure result means.
Products
Static ISP proxies: residential IPs on consumer networks
Static ISP proxies in the United States and Vietnam: fixed IPs registered to consumer internet providers, rented to one customer, with unmetered traffic.