How to Use pip with Proxy: Step-by-Step Guide

Quick Overview: 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 Up pip Proxy via Command Line

One quick way to use pip with a server is to provide the proxy server 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 server 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 Proxy in pip Config File

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 server 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. Python will apply the server 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.

Method 3: Use 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.

Testing Your Proxy Configuration

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-2023.5.7 charset-normalizer-3.1.0 idna-3.4 requests-2.30.0 urllib3-2.0.3

pip Proxies in Virtual Environments

• Inherit Environment Settings: Any current server setup is respected by install without further actions as a virtual environment immediately picks up the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY variables.
• Use Existing pip Config: Pip within the venv still shows your user-level pip.conf / pip.ini. One server corresponds to http://… input there powers every project and saves you from repeating settings.
• Per-Environment Config (Optional): Does one project call for various rules? Directly at the venv’s root place a pip.conf (Linux/macOS) or pip.ini (Windows). This site-specific file replaces user and global settings, therefore providing per-project control over proxy server behavior while leaving other contexts unaltered.

Troubleshooting Common Proxy Issues

• 407 Proxy Authentication Required: The server turned down 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.

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.