How to Set Up a Proxy for pip: --proxy, pip.conf and Environment Variables

What a proxy changes and what it does not

A proxy changes only the network path between your computer and the package index. It does not change which index pip downloads from: that is the separate --index-url setting, so a proxy and a mirror are different things. This guide is about the pip command itself; for proxies inside Python code that uses the requests library, see the requests guide.

• requests proxy guide

Three ways to set it, and which one wins

The pip configuration page gives the order: command-line options first, then environment variables, then configuration files. In a configuration file, a section for one command, such as [install], overrides the same setting in [global]. So a --proxy typed on the command line always beats a proxy saved in a file. For a quick test use the command line; for every day use the file.

• Sources:
• pip docs: Configuration

One command with --proxy

The pip user guide describes --proxy in the form scheme://[user:passwd@]proxy.server:port. The scheme is http for the Proxy302 HTTP port. The user guide runs pip as python -m pip, which makes sure the pip of that Python is used; on Windows the py launcher works the same way (py -m pip). Nothing is saved: the next command goes direct again.

• Sources:
• pip docs: User Guide (using a proxy server)
• pip docs: pip command reference (general options)

One command with --proxy: example

python -m pip install --proxy http://USERNAME:PASSWORD@HOST:PORT requests

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

Username and password

If the username or password contains characters such as @, : or /, write them in percent-encoded form: @ becomes %40, : becomes %3A and / becomes %2F. The pip pages do not describe this rule, so test the setting with the check below. Copying the values from My assets is safer than typing them. A password in a command stays in your shell history, and a password in a config file can be read by anyone who can read that file.

• Sources:
• pip docs: pip command reference (general options)

Save it in the pip config file

The simplest way is the pip config command: pip config set global.proxy ... writes the setting for you, and pip config unset global.proxy removes it. Without --user, --global or --site, pip uses the virtual environment's file when one is active and the file exists, and otherwise the user file. To edit by hand, the user file is $HOME/.config/pip/pip.conf on Linux, %APPDATA%\pip\pip.ini on Windows, and on macOS the file under $HOME/Library/Application Support/pip if that folder exists, otherwise $HOME/.config/pip/pip.conf. Option names in the file are the long option names without the dashes in front, so --proxy becomes proxy. pip config debug lists which files exist and the values in each, which is the quickest way to find the file.

• Sources:
• pip docs: Configuration
• pip docs: pip config

Save it with pip config: example

python -m pip config set global.proxy http://USERNAME:PASSWORD@HOST:PORT
python -m pip config list

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

The same setting in pip.conf: example

[global]
proxy = http://USERNAME:PASSWORD@HOST:PORT

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

Environment variables

The user guide lists the standard variables http_proxy, https_proxy and no_proxy. The configuration page adds that any option can also be given as PIP_ plus the upper-case option name, so PIP_PROXY works as well. If a proxy is already set in the environment and you want pip to ignore it, add --no-proxy-env, which makes pip not read proxy configuration from environment variables. On Windows Command Prompt use set instead of export.

• Sources:
• pip docs: User Guide (using a proxy server)
• pip docs: Configuration
• pip docs: pip command reference (general options)

Environment variables for one session: example

export https_proxy=http://USERNAME:PASSWORD@HOST:PORT
export http_proxy=http://USERNAME:PASSWORD@HOST:PORT
export no_proxy=localhost,127.0.0.1
python -m pip install requests

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

Proxy or mirror?

--proxy changes the path, --index-url changes the address pip asks. The configuration page uses pip config set global.index-url as its own example for the second. They can be used together, and each one is set on its own. If pip can reach the index you want without a proxy, you do not need a proxy at all.

• Sources:
• pip docs: Configuration
• pip docs: pip config

SOCKS5

The pip user guide and command-line reference describe only the form scheme://[user:passwd@]proxy.server:port and do not say which schemes pip accepts or whether SOCKS needs extra packages. So this guide uses HTTP only. Choose HTTP when you generate the Proxy302 proxy.

• SOCKS5 proxies page

• Sources:
• pip docs: User Guide (using a proxy server)
• pip docs: pip command reference (general options)

How to switch the proxy off

Run pip config unset global.proxy (use the same section name you set), then pip config list to see what is left. If a proxy still applies, unset the http_proxy and https_proxy variables in that terminal. For a single run without touching anything, add --no-proxy-env to ignore the variables. PIP_CONFIG_FILE set to os.devnull disables loading all configuration files, as the configuration page says, which is a quick way to test without your saved settings.

• Sources:
• pip docs: pip config
• pip docs: Configuration
• pip docs: pip command reference (general options)

How to check that pip uses the proxy

1. Print what is set

   Run python -m pip config list. It shows the active configuration; python -m pip config debug shows which files exist and what each one holds.

2. Check the exit address with curl

   The second command below shows the IP, country and network that websites see through the same proxy.

   • how to check your proxy's IP, country and ISP

3. Run a small download with more output

   Add -v for more output (it can be used up to three times). If the download works with the proxy set and fails when the proxy address is wrong, pip is using it.

How to check that pip uses the proxy: example

python -m pip config list
curl -x http://USERNAME:PASSWORD@HOST:PORT https://ipinfo.io/json
python -m pip download six --no-deps -d ./pip-test -v

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

Common errors

• 407 Proxy Authentication Required. The proxy rejected the username or password. Copy them again and check the percent-encoding.

• ProxyError, or the connection times out. Wrong HOST or PORT, or the lease has ended. Test the same address with the curl command above. The pip reference gives the socket timeout as 15 seconds by default and the retries as 5; --timeout and --retries change them.

• pip ignores the setting. Run pip config list and look for a --proxy on the command line, a PIP_PROXY variable or a [install] section that overrides the one you edited.

• A package from your company's own index fails. Add its host to the no_proxy variable so that pip reaches it directly.

• authentication required guide
• connection failed guide

• Sources:
• pip docs: pip command reference (general options)

How to do it with Proxy302

Every command here needs only the host, port, username and password of a Proxy302 proxy. pip takes an HTTP address, so choose HTTP when you generate the proxy. Rotating residential traffic is billed per GB and the exit country is set when you generate the proxy; HTTP is on port 2222 and SOCKS5 on port 3333 of proxy.proxy302.com. A static ISP IP stays fixed for the whole lease and does not rotate, which suits a tool that you want to always leave from the same address. HTTP or SOCKS5 is chosen when you buy, and one IP carries one protocol.

• rotating residential page
• SOCKS5 proxies page

• Sources:
• Proxy302 product facts and price list

How to do it with Proxy302: steps

1. Step 1

   Open the rotating residential page, choose the line, keep Protocol on HTTP, then click Review cost and generate.

2. Step 2

   Open My assets (the console page that holds everything you bought) and copy HOST, PORT, USERNAME and PASSWORD. The Connect page shows a ready example with your own endpoint.

3. Step 3

   Put the values into the commands above.

4. Step 4

   Confirm the exit with https://ipinfo.io/json through the proxy.

   • how to check your proxy's IP, country and ISP

5. Step 5

   From mainland China, start the helper tool from the Connect page first and keep it open while you use the proxy.

   • Helper tool guide

Prices and limits

The Budget line costs US$1.50 per GB, US$1.35 per GB in a 100 GB package and US$1.20 per GB at 300 GB. A static ISP IP costs US$0.50 for one day and US$7.99 for 30 days. There is no free trial, and the smallest purchase is 1 GB or one IP for one day. Which exit locations are available changes daily.

• Sources:
• Proxy302 product facts and price list

FAQ

Read next

Python requests proxy setup

How to use HTTP and SOCKS5 proxies in Python requests: examples, timeouts and an IP check.

npm proxy setup

Set a proxy for npm with npm config, .npmrc or environment variables, handle pnpm and Yarn, switch it off and check it with npm ping.

407 Proxy Authentication Required

HTTP 407 Proxy Authentication Required comes from the proxy server, not from the website you are trying to reach.

Fix ERR_PROXY_CONNECTION_FAILED

The ERR_PROXY_CONNECTION_FAILED error appears in Chrome and Edge when the browser cannot establish a connection with a proxy server.