How to Use pip With a Proxy: Step-by-Step Setup, Config, and Fixes

Quick Answer: Three Ways to Set a pip Proxy

If you only need the command, here it is. Point pip at your proxy for a single install, for every install, or for every tool on the machine.

One command only:

pip install –proxy http://user:password@proxy.company.com:8080 requests

Every pip command (writes to your user config file):

pip config set global.proxy http://user:password@proxy.company.com:8080

Every tool in the shell, not just pip:

export https_proxy=”http://user:password@proxy.company.com:8080″

Which one you pick depends on how long the setting has to live:

Method	Setting lives in	Best for
--proxy flag	The single command	Testing a proxy, one-off installs, CI steps that need a different route
pip config file	pip.conf / pip.ini	A developer workstation that always sits behind the same proxy
Environment variables	Your shell or system	Docker images, CI runners, and machines where curl and npm need the proxy too

Each method is covered in full below, along with how to turn the proxy off again, how to reach an internal PyPI mirror, and how to read the errors pip throws when the proxy blocks it.

Why Use a Proxy with pip?

Corporate firewalls, university networks, and on-prem servers often block direct internet access on their network interfaces, so downloads from PyPI fail without a proxy server. A proxy server tunnels outbound traffic through an approved gateway, so Python pip install with proxy becomes the safe, compliant path to PyPI. When it sees a request from Python originating at restricted ip addresses, it forwards it to PyPI on your behalf, letting Python install reach public or private indexes while staying within security policy. Python makes this easy to use: it supports both HTTP and HTTPS proxies out-of-the-box and can be pointed at them three ways—add –proxy on the CLI, drop a proxy = http://… line into pip.conf/pip.ini, or export HTTP_PROXY and HTTPS_PROXY environment variables. 

Method 1: Set the pip Proxy With the –proxy Flag

One quick way to use pip with a server is to provide your proxy details as a command-line option when installing packages. This is useful for one-time installation or testing connectivity.

Syntax: Use the –proxy option with the URL of your proxy, including optional user:password@credentials. The format should be scheme://[user:password@]proxy.server:port. For example, if your proxy address is proxy.company.com on port 8080:

pip install --proxy http://proxy.company.com:8080 <package-name>

If the server requires authentication, use a URL that supplies your username and password (note: special characters in the password may need URL encoding). For example:

pip install --proxy http://username:password@proxy.company.com:8080 requests

In the above, replace username:password with your actual credentials, and proxy.company.com:8080 with your server’s host and port. Python will route the download—and any metadata processing—of the requests package through the given proxy server. The –proxy option can be used with any subcommand that needs internet access. Keep in mind that you’ll need to include this option each time pip runs, and make sure the command is tested with a small package first for frequent use. For a more permanent solution, consider using a config file or environment variable as shown in the next methods.

Method 2: Configure the Proxy in pip.conf / pip.ini

Pip allows you to store server settings in configuration files, so you don’t have to type them every time. By adding your server settings to Python’s config file, every pip command will use the proxy server automatically.

Where to Find/Create the pip Config File

Pip looks for config files in standard locations depending on your OS:

• Linux/macOS (User Level): The user config file is typically located at ~/.config/pip/pip.conf on modern systems. (It will also read a legacy config at ~/.pip/pip.conf if it exists.) On macOS, you can also use ~/Library/Application Support/pip/pip.conf if that directory exists. If the file doesn’t exist yet, you’ll need to create it along with the enclosing directories.
• Windows (User Level): On Windows, the config file is named pip.ini and is stored in your %APPDATA%\pip\ directory. For example, for a user named Alice on Windows 10, the file path would be C:\Users\Alice\AppData\Roaming\pip\pip.ini. You may need to create the Python pip folder under AppData\Roaming if it’s not there, then create a file named pip.ini inside it.

Note: There are also system-wide (“global”) config files (e.g. /etc/pip.conf on Linux or C:\ProgramData\pip\pip.ini on Windows), as well as “site” config files for specific virtual environments. In most cases, using the per-user config is sufficient and avoids needing administrator rights.

Linux/macOS Example

On a Linux or macOS machine, create (or open) the file ~/.config/pip/pip.conf for your user. If the pip.conf file doesn’t exist, create a new text file with that name. Then add the following lines to set your server:

[global]
proxy = http://username:password@proxy.company.com:8080

This uses a standard INI configuration format. The [global] section means the setting applies to all Python commands by default. Replace username:password with your actual credentials—special characters must be URL-encoded. If your server does not require a username/password, just use proxy = http://proxy.company.com:8080, not supporting embedded credentials. Save the file.

Now, any Python command you run will read the configuration that was provided in pip.conf. For example, running Python pip install flask will automatically use the server address you configured, without needing –proxy on the command line.

Windows Example

On Windows, open the file %APPDATA%\pip\pip.ini (create it if it doesn’t exist). Add the same content in INI format:

[global]
proxy = http://username:password@proxy.company.com:8080

Again, substitute your actual proxy details. For instance, if your server is at proxy.corp.local:3128 and no auth is required, the line would be proxy = http://proxy.corp.local:3128. Make sure to include the [global] header as shown. Once you save this pip.ini file, Python will automatically pick up the server setting for all operations.

What to Put Inside the Config File

The only thing you must include is the server setting itself under the [global] section. The key name is literally “proxy”, corresponding to the –proxy option. You do not need to add http_proxy or https_proxy keys here – config uses the single proxy setting for any URL scheme. If you have both HTTP and HTTPS proxies and they differ, typically you can just use the HTTPS proxy for all traffic. It will use the given server for both HTTP and HTTPS requests, requiring no extra flags once configured. After adding the server setting and saving the file, you’re done.

To verify, you can run a Python command (like download <package>) and check if it succeeds. pip will apply the proxy from the config automatically, so you shouldn’t see proxy-related errors. If you ever need to disable the server, use one of two methods: remove or comment out this line, or use the –proxy “” command-line option to override it on a case-by-case basis.

Manage the Proxy with pip config Commands

You do not have to open the file by hand. Pip ships a config subcommand that writes the same lines for you, and it always picks the correct path for your OS:

pip config set global.proxy http://username:password@proxy.company.com:8080

A common point of confusion: global here is the section name inside the file, not the scope of the change. By default pip writes to your per-user file. To choose the scope explicitly, add a level flag:

• --user – the per-user file, the default. No admin rights needed.
• --global – the system-wide file (/etc/pip.conf, C:\ProgramData\pip\pip.ini). Requires elevated rights.
• --site – the file inside the currently active virtual environment.

To see what pip has actually loaded, and from which file, run:

pip config list -v
pip config debug

The first prints every active setting with the file it came from; the second dumps the full search path, which is the fastest way to find a stale proxy line someone left in a system config years ago. To remove the setting again:

pip config unset global.proxy

Method 3: Use HTTP_PROXY and HTTPS_PROXY Environment Variables

Another common way and other command-line package managers—to use a server is by setting environment variables. This approach has the benefit of being global to your shell or system – any application that respects these environment variables (curl, npm, etc.) will use the proxy server, which is convenient in a controlled environment.

The standard environment variables for proxies are:

• HTTP_PROXY – the URL of your proxy server for HTTP traffic.
• HTTPS_PROXY – the URL of your proxy server for HTTPS traffic.
• NO_PROXY – a list of hostnames or domains that should not go through the proxy server (optional, e.g. internal sites).

It will check these variables automatically. (On case-sensitive systems like Linux, use lowercase http_proxy/https_proxy in shells. On Windows, environment variables are case-insensitive, but it’s common to set them as uppercase.)

Linux/macOS Syntax

In a Linux or macOS terminal (assuming a Bash or similar shell), you can export the server environment variables like so:

export http_proxy="http://username:password@proxy.company.com:8080"
export https_proxy="http://username:password@proxy.company.com:8080"
export no_proxy="localhost,127.0.0.1,.company.internal"

After running these export commands, any subsequent Python install in that session will use the proxy—ensuring the latest versions are reachable even inside restricted shells. For a permanent setup, you can add these lines to your shell’s startup file (like ~/.bashrc or ~/.zshrc), or on Linux, you could add them to the system-wide /etc/environment file so they apply to all users. Remember to keep your server credentials secure; if you’re adding to a shared system file, you might want to use a credentials manager or a more secure method if possible.

Windows Syntax

On Windows, you can set environment variables for proxies in the Command Prompt or PowerShell.

For a single session in Command Prompt, use the set command:

C:\> set HTTP_PROXY=http://username:password@proxy.company.com:8080
C:\> set HTTPS_PROXY=http://username:password@proxy.company.com:8080

These will last only until you close the command prompt. To set the variables permanently (so they persist across sessions), you can use the setx command:

C:\> setx HTTP_PROXY "http://username:password@proxy.company.com:8080" /M
C:\> setx HTTPS_PROXY "http://username:password@proxy.company.com:8080" /M

The /M flag sets it for the whole machine (system-wide). You’ll need to open a new command prompt (or log out and in) for these to take effect. Alternatively, you can set environment variables via the Windows GUI (System Properties -> Environment Variables) which achieves the same result.

If you’re using PowerShell, you can set an environment variable for the session like this:

PS C:\> $Env:HTTP_PROXY = "http://username:password@proxy.company.com:8080"
PS C:\> $Env:HTTPS_PROXY = "http://username:password@proxy.company.com:8080"

After setting these, try running command in the same PowerShell session to verify it works. Like with Linux, you may also set NO_PROXY (or no_proxy) if certain domains should bypass the proxy server.

How to Disable or Bypass the Proxy in pip

Sooner or later you will need pip to ignore the proxy, you moved to a home network, you are installing from a local wheel, or the proxy itself is what broke the install. There are three levels at which you can switch it off.

Override it for one command. Passing an empty string to --proxy beats anything set in the config file or the environment, and only for that command:

pip install –proxy “” requests

Remove it permanently. If the proxy came from a config file, drop the key:

pip config unset global.proxy

Clear the environment variables. These outlive the config file in most CI images, so unset them explicitly:

Linux/macOS

unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY

Windows Command Prompt

set HTTP_PROXY=

set HTTPS_PROXY=

PowerShell

Remove-Item Env:HTTP_PROXY
Remove-Item Env:HTTPS_PROXY

Bypass it for specific hosts only. When most traffic must go through the proxy but your internal index must not, list the exceptions in NO_PROXY instead of turning the proxy off:

export no_proxy=”localhost,127.0.0.1,.company.internal,nexus.company.com”

Note that pip reads NO_PROXY from the environment only — there is no no-proxy key in pip.conf. If you need the exception to survive a reboot, put the export in your shell startup file or in the machine’s environment settings.

Testing Your Proxy Configuration

Check Which Proxy pip Is Actually Using

Before testing an install, confirm that pip picked up the setting you expect. Config files, environment variables, and command-line flags stack in a fixed order, and a forgotten system-wide file is a classic reason a “correct” setup keeps failing:

pip config list -v

The order of precedence, from weakest to strongest, is: system config file, then per-user config file, then the active virtual environment’s config, then environment variables, then the --proxy flag on the command line. Whatever sits furthest to the right wins.

To make a request through the proxy without actually installing anything, use a dry run:

pip install –dry-run –ignore-installed requests

If that returns package metadata, the proxy is reachable and authenticated. If it hangs or throws, jump to the troubleshooting section below.

Linux/macOS

Open a new terminal (to ensure any environment changes are applied) and try installing a small package, for example requests:

$ pip install requests
Collecting requests

 Downloading requests-2.30.0-py3-none-any.whl (62 kB)

  ---------------------------------------- 62.0/62.0 kB 2.0 MB/s eta 0:00:00

Collecting charset-normalizer<4,>=2

 Downloading charset_normalizer-3.1.0-py3-none-any.whl (50 kB)

  ---------------------------------------- 50.0/50.0 kB 1.3 MB/s eta 0:00:00

Collecting idna<4,>=2.5

 Downloading idna-3.4-py3-none-any.whl (61 kB)

  ---------------------------------------- 61.5/61.5 kB 1.5 MB/s eta 0:00:00

Collecting urllib3<3,>=1.21.1

 Downloading urllib3-2.0.3-py3-none-any.whl (123 kB)

  ---------------------------------------- 123.6/123.6 kB 2.5 MB/s eta 0:00:00

Collecting certifi>=2017.4.17

 Downloading certifi-2023.5.7-py3-none-any.whl (156 kB)

  ---------------------------------------- 156.7/156.7 kB 3.1 MB/s eta 0:00:00

Installing collected packages: certifi, urllib3, idna, charset-normalizer, requests

Successfully installed certifi-2023.5.7 charset-normalizer-3.1.0 idna-3.4 requests-2.30.0 urllib3-2.0.3

Windows

On Windows, the testing process is similar. Open a new Command Prompt (or PowerShell) after setting up the server config or variables. Then run:

C:\> pip install requests
Collecting requests

 Downloading requests-2.30.0-py3-none-any.whl (62 kB)

  ---------------------------------------- 62.0/62.0 kB <speed> <time>

Collecting certifi>=2017.4.17

 Downloading certifi-2023.5.7-py3-none-any.whl (156 kB)

  ---------------------------------------- 156.7/156.7 kB <speed> <time>

... (additional output omitted for brevity) ...

Successfully installed certifi-2026.x charset-normalizer-3.1.0 idna-3.4 requests-2.32.x urllib3-2.3.x

pip Proxies in Virtual Environments

• Inherited environment settings: A virtual environment picks up HTTP_PROXY, HTTPS_PROXY, and NO_PROXY from the parent shell automatically. Nothing extra to configure.
• Existing pip config: Pip inside the venv still reads your user-level pip.conf or pip.ini. One proxy line there covers every project on the machine.
• Per-environment config (optional): If one project needs different rules, drop a pip.conf (Linux/macOS) or pip.ini (Windows) in the venv root. This site-level file overrides the user and global settings for that environment only, leaving everything else untouched.

Using pip Behind a Corporate Proxy: Internal Mirrors, 403s, and Offline Installs

A proxy that lets your browser out does not automatically let pip reach PyPI. Many corporate gateways allow the connection but block the package host, or replace public PyPI with an internal mirror altogether. If your proxy is configured correctly and installs still fail, the problem is usually the index, not the proxy.

Point pip at an Internal PyPI Mirror

Most companies run a private index: Nexus, Artifactory, devpi, or Azure Artifacts. That caches PyPI on the inside of the firewall. Aim pip at it and the proxy stops mattering for package downloads:

pip install –index-url https://nexus.company.com/repository/pypi-proxy/simple mypackage

To make it permanent, write it into the config file next to the proxy line:

pip config set global.index-url https://nexus.company.com/repository/pypi-proxy/simple
pip config set global.trusted-host nexus.company.com

If you need the internal index in addition to PyPI rather than instead of it, use --extra-index-url. Keep in mind that pip searches every listed index and installs the highest version it finds, so an internal index should host your private packages, not shadowed copies of public ones.

Fixing 403 Errors from files.pythonhosted.org

A common failure looks like the metadata request succeeding and the download failing. That happens because pip talks to two hosts: pypi.org serves the index, files.pythonhosted.org serves the wheels. Allow-lists that only cover the first one produce a 403 halfway through the install.

Ask your network team to allow both hosts, and while you wait, mark them trusted so pip does not additionally trip over TLS interception:

pip install –trusted-host pypi.org –trusted-host files.pythonhosted.org requests

Treat --trusted-host as a diagnostic, not a fix — it disables certificate verification for those hosts. The proper solution is the CA bundle below.

Handling a Proxy That Intercepts TLS

Corporate proxies frequently decrypt HTTPS and re-sign it with their own certificate authority, which Python does not trust out of the box. Point pip at the corporate CA bundle instead of switching verification off:

One command:

pip install –cert /etc/ssl/certs/corporate-ca.pem requests

Permanently, for pip:

pip config set global.cert /etc/ssl/certs/corporate-ca.pem

For every Python tool that uses requests:

export PIP_CERT=/etc/ssl/certs/corporate-ca.pem
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/corporate-ca.pem

On Windows the bundle is usually a .crt or .pem exported by IT; the same flags apply, with a Windows path.

Installing Packages With No Network at All

When the proxy is not going to be opened for you, move the packages by hand. Download them on a machine that has access, then install from the local folder:

On a machine with internet access:

pip download requests -d ./wheels

Copy ./wheels across, then on the restricted machine:

pip install –no-index –find-links=./wheels requests

pip download pulls the package and every dependency, so the folder is self-contained. Two things to watch: wheels are platform and Python-version specific, so download on a matching OS and interpreter, and add --platform, --python-version, and --only-binary=:all: if the two machines differ. For a whole project, run pip download -r requirements.txt -d ./wheels and install with the same --no-index --find-links pair.

Can pip Use a SOCKS5 Proxy?

Yes, but not on a stock install. Pip only understands HTTP and HTTPS proxy URLs until you add SOCKS support, which comes from the PySocks package:

pip install pysocks
pip install –proxy socks5h://127.0.0.1:1080 requests

Use the socks5h:// scheme rather than socks5://. The trailing h tells pip to resolve DNS through the proxy, which is what you want when the restricted network cannot resolve pypi.org in the first place.

There is an obvious chicken-and-egg problem: installing PySocks requires network access. If the SOCKS proxy is your only route out, download the PySocks wheel on another machine and install it from the file first, as described in the offline section above. Once it is in place, every pip command in that environment can use a SOCKS URL, including in pip.conf.

Troubleshooting Common Proxy Issues

• 407 Proxy Authentication Required: The proxy rejected the request if credentials are incorrect or absent. Verify either your system is already authenticated using NTLM/Kerberos or double-check the http://user:pass@proxy:port format (URL-encode special characters). When single sign-on is needed, tools as CNTLM can broadcast credentials.
• SSL Certificate Verify Errors: Corporate proxies—which Python does not trust—often intercept HTTPS using a bespoke CA. Either add –cert /path/ca.pem or import the CA bundle of the server and set PIP_CERT or REQUESTS_CA_BUNDLE. Use –trusted-host pypi.org (less safe) for rapid tests.
• 403 Forbidden Errors: Access was known but blocked—probably in line with the policy or PyPI rate-limits of the server. Verify your are using the right repository URL, confirm the server allow-list contains PyPI domains, or switch to an approved internal mirror or Artifactory feed.

ProxyError: Cannot connect to proxy

ProxyError(‘Cannot connect to proxy.’, NewConnectionError(…: Failed to establish a new connection))

Pip never reached the proxy at all. Check the three things that break most often, in this order: the host and port are correct and reachable (curl -v telnet://proxy.company.com:8080 or Test-NetConnection proxy.company.com -Port 8080 on Windows), the proxy is actually running on that port, and no local firewall or VPN split-tunnel is intercepting the connection first. If a VPN client is active, the proxy may only be reachable while the tunnel is up.

ValueError: check_hostname requires server_hostname

This one is misleading — it is not a certificate problem. It appears when the proxy URL uses the https:// scheme:

proxy = https://proxy.company.com:8080

Almost every corporate proxy speaks plain HTTP on the connection between you and it, even when the traffic it forwards is HTTPS. Change the scheme to http:// and the error disappears. If you genuinely have an HTTPS-terminating proxy, upgrade pip and urllib3 to current versions, which handle it correctly.

OSError: proxy URL had no scheme

ERROR: Could not install packages due to an OSError: Proxy URL had no scheme, should start with http:// or https://

The proxy value is missing its protocol. proxy.company.com:8080 is not a valid proxy URL — pip needs http://proxy.company.com:8080. Check the config file and every environment variable, since one of them may be set without the scheme while the others look fine.

Read timed out / connection to pypi.org timed out

The proxy accepted the connection but the response never came, usually because of deep packet inspection or a slow gateway under load. Give pip more room before assuming the setup is wrong:

pip install –timeout 60 –retries 5 requests

If that succeeds, make it permanent with pip config set global.timeout 60. If it still times out, the gateway is probably dropping the package host rather than throttling it — see the 403 section above.

SSL: UNEXPECTED_EOF_WHILE_READING

SSLError(SSLEOFError(8, ‘EOF occurred in violation of protocol’))

The TLS handshake was cut short mid-way, which is what an intercepting proxy looks like when its certificate chain is not installed on your machine. Install the corporate CA and point PIP_CERT at it as described in the corporate proxy section. Bumping --timeout sometimes helps if the handshake is merely slow, but a persistent EOF is almost always the CA.

407 on Windows with a domain account

If your proxy authenticates with NTLM or Kerberos, embedding user:password in the URL will not work — pip cannot perform the challenge-response handshake. Either run a local authenticating relay such as CNTLM or px and point pip at http://127.0.0.1:3128, or ask for a service account with basic authentication. When the password contains special characters, URL-encode them: @ becomes %40, # becomes %23, : becomes %3A.

pip Proxy in Docker, CI/CD, and Other Python Tools

Everything above applies to a workstation. Build agents and containers add one wrinkle: they start from a clean environment every time, so the proxy has to be injected rather than configured once.

Docker. Pass the proxy at build time so it does not get baked into the image layers:

docker build
–build-arg HTTP_PROXY=http://proxy.company.com:8080
–build-arg HTTPS_PROXY=http://proxy.company.com:8080
–build-arg NO_PROXY=localhost,127.0.0.1
-t myapp .

Docker forwards these to RUN steps automatically, so RUN pip install -r requirements.txt picks them up with no changes to the Dockerfile. Never write credentials into a Dockerfile with ENV — they stay in the published image.

GitHub Actions, GitLab CI, and Jenkins. Set the variables at the job level and store the credentials as a secret:

env:
HTTPS_PROXY: ${{ secrets.CORP_PROXY_URL }}
NO_PROXY: localhost,127.0.0.1,nexus.company.com

pip3. On systems where both Python 2 and 3 exist, pip3 is the same program with the same config files. A proxy set for pip applies to pip3 as long as both point at the same interpreter — run pip3 config list -v to confirm which file it reads.

pipx. It calls pip under the hood, so HTTP_PROXY and HTTPS_PROXY are enough for most cases. To pass flags through explicitly:

pipx install –pip-args=”–proxy http://proxy.company.com:8080″ black

Pipenv, Poetry, and uv. All three respect the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY variables, which is the simplest way to configure them. Poetry and uv also accept a custom index, so an internal mirror can be set once in pyproject.toml rather than per command. For certificate interception, uv reads SSL_CERT_FILE, and Poetry reads REQUESTS_CA_BUNDLE.

conda. Conda does not read pip.conf. Add the proxy to .condarc instead:

proxy_servers:
http: http://user:password@proxy.company.com:8080
https: http://user:password@proxy.company.com:8080

Conclusion

Pip behind a proxy reduces to three options: add –proxy for one-offs, set proxy =… Export HTTP_PROXY and HTTPS_PROXY to cover every tool in your shell, or establish a persistent per-user configuration in pip.conf/pip.ini Run a quick test: use a few Python pip installs and verify the latest versions download cleanly across every Python versions you support, and tweak if needed. Save this guide so your Python tools follow network regulations everywhere they take you.