There are various scenarios of proxy server use, but proxies are often needed in IT projects, especially when writing custom parsers or building complex web applications or services. In this article, we will explain how to use a proxy with pip, whether it is possible to configure proxies for specific connections or at the level of global environment variables, and how to do this (with detailed instructions). We will also share the list of the most common errors and troubleshooting methods for using pip through a proxy.
In short, pip is the standard package manager in the Python programming environment. Alternatives to it include conda (for the Anaconda environment), poetry, pipenv (which combines a virtual environment manager, virtualenv, and pip), and buildout (formerly popular for working with large-scale Python projects).
Technically, pip solves the following tasks:
Proxy servers are intermediary nodes. They are used for various tasks:
In short, a proxy is a tool for organizing alternative Internet routes and managing data streams.
There are different types and kinds of proxies: transparent and anonymous, rotating (back connect scheme) and non-rotating, HTTP/HTTPS, SOCKS, SSH, etc. (depending on supported protocols), residential, mobile, and datacenter (by type of outgoing addresses), caching proxies, with compression, etc. Each proxy type has its use cases and connection features.
For example, when working with parsers, rotating HTTP or SOCKS proxies based on mobile or residential IPs (residential proxies) makes sense. For corporate traffic management tasks, datacenter proxies may be more appropriate.
We must still explain how the Python package manager and a proxy are related. Earlier, we mentioned that pip downloads libraries and code from the PyPI repository. However, this approach can be inconvenient in some instances, such as when:
Proxies are required to redirect traffic to the appropriate point. Moreover, a proxy server can perform additional tasks, such as caching static content (including Python script files), checking for viruses and malicious content, and compressing files (to save bandwidth and speed up downloads).
As a result, several issues are solved simultaneously: security is enhanced, traffic and request control are simplified, and content management becomes possible.
The pip package manager can connect to a proxy in several ways, including special command syntax, environment variables, virtual environments, and configuration files.
Below, we’ll go through each way of connecting pip to a proxy in detail.
The standard pip syntax looks like this:
pip install <package name>
Call the executable file directly if you haven't added pip to your environment variables. For example, on Windows, it might look like this:
cd "C:\Program Files\Python313\Scripts\"./pip.exe install <package name>
The installation path for pip might differ. In this case, pip was installed in the shared "Program Files" directory, and the Python version is 3.13.
If Python is added to the environment variables without pip, you can use the following command:
python -m pip install <package name>
Instead of the “install” command, you can use others: download (to download the specified package only), uninstall (to remove packages), freeze (to “freeze” the packages), list (to display installed packages), search (to search for packages), etc.
Note: there’s no separate command for updating, but the “install” command has a flag for it:
pip install --upgrade <package name>
The proxy is also specified via a special flag in the pip install command (--proxy). The full command will look like this:
pip install --proxy http://123.455.234.345:3088 <package name>
You should replace the connection data with your own (IP address and port number).
If the proxy uses a domain, the pip connection string would look like this:
pip install --proxy http://proxy-url.com:3088 <package name>
Many rotating proxies require mandatory authentication to secure connections. Connecting pip to a proxy in this case will look like this:
pip install --proxy http://proxy_user:PASSWRD@123.455.234.345:3088 <package name>
You can notice that the structure hasn’t changed a lot — only the authentication parameters have been added.
Naturally, you need to replace the placeholder values with your credentials (provided by your proxy service).
Perfect proxies for accessing valuable data from around the world.
If you don't want to specify proxy parameters manually every time you use pip, you can try setting the connection details in configuration files or adding them to environment variables.
Let's discuss each approach separately.
Pip can use its configuration files. They are not always stored centrally. It’s better to ask pip directly where it looks for configuration files to avoid guessing.
To do this, type the following command:
pip config -v list
In Windows, configuration files will be picked up from the following directories:
The Python installation path may differ in your case, so instead of "C:\Program Files\Python313", it could be another path.
Open the required file and add the following lines:
[global]proxy = http://proxy_user:PASSWRD@123.455.234.345:3088
(with your actual connection data)
If the file doesn’t exist, just create it: right-click in the folder, select "New" → "Text Document," then rename it and change the extension to .ini. You should get the “pip.ini”.
On Linux or macOS, the configuration files have a .conf extension and are located in other directories.
For Linux distributions (in most cases):
For macOS:
The priority order is assigned to those notes that are defined at the latest level:
In Windows, you can set environment variables through a special interface. Search for "Environment variables" in the system search or open System Properties and click the "Environment Variables" button.
Create the following new variables:
If the proxy does not require authentication, the format will look something like this:
http://123.455.234.345:3088 or http://proxy-domain.com:3008
Be sure to provide the port number, address, username, and password (the ones above are just examples and do not work).
Note: HTTP_PROXY and HTTPS_PROXY are different variables; you must set both.
Using environment variables allows you to configure a system-wide Python proxy (and other script runtime environments).
Instead of using the graphical interface, you can use the command line:
For Windows:
set HTTP_PROXY=http://proxy_user:PASSWRD@123.455.234.345:3088set HTTPS_PROXY=https://proxy_user:PASSWRD@123.455.234.345:3088
For Linux
export http_proxy=http://proxy_user:PASSWRD@123.455.234.345:3088export https_proxy=https://proxy_user:PASSWRD@123.455.234.345:3088
If you want to set a list of exceptions (sites that should bypass the proxy), list them in the no_proxy variable. For example:
set NO_PROXY=example.com,site123.org,127.0.0.1
To remove a variable in Linux, use the unset command:
unset HTTP_PROXY
In Windows, it's easier to set an "empty" proxy to effectively remove it:
set HTTP_PROXY=
Or, you can fully reset proxy settings with administrator rights:
netsh winhttp reset proxy
Recently, Python introduced a CLI interface for managing pip settings.
You can now define global, user-level, and virtual environment-specific configurations directly from the command line. The syntax is not dependent on the platform.
Here is how the command to install a proxy will look on the global level:
pip config set global.proxy http://proxy.host:1234
or
pip config set global.proxy http://login:pass@proxy.host:1234
(if authorization is used with login and password)
Here is how settings are defined on the user level:
pip config set user.proxy http://login:pass@proxy.host:1234
And here is how they are defined for the «site» level (environment variables):
pip config set site.proxy http://login:pass@proxy.host:1234
You can set or change the environment variable directly within Python scripts like this:
PIP_PROXY = http://login:pass@proxy.host:1234
This will be a complete equivalent for running the command «pip --proxy http://login:pass@proxy.host:1234».
Don't forget to use the actual credentials to connect to your proxy.
If you need to install a package using pip through a proxy for a specific virtual environment, use the following syntax:
C:\Users\<YOUR_NAME>\myvenv\Scripts\pip install --proxy=http://proxy-user:passwd@proxy_address:1234 virtualenv
In other words, you need to call the pip executable directly within your virtual environment.
If the direct path doesn't work, navigate to the correct directory first:
cd “C:\Users\<YOUR_NAME>\myvenv\Scripts\pip”./pip.exe install --proxy=http://proxy-user:passwd@proxy_address:1234 <package name>
You can also configure general proxy settings for the current virtual environment. This is done via the standard environment variables we reviewed earlier (HTTP_PROXY and HTTPS_PROXY):
Some of the most complex configuration errors involve proxies being defined in different config files, for other users and at various access levels (globally, in environment variables, etc.). It can be pretty challenging to figure out what is set and where.
A centralized proxy configuration mechanism may be used in large corporate networks, often involving NTLM authentication (also used in proxy servers like NTLMAPS and CNTLM).
When running pip, misconfigured settings can often be quickly fixed by specifying the proxy parameters directly in the command line. These settings have the highest priority.
However, simply specifying the proxy address and port is not enough. Other configuration options can also cause errors.
This is rare but quite possible. To verify if PyPI works, connect to it directly (without a proxy) or through another (known-working) proxy.
At the very least, you should verify that the proxy is available and functions correctly (and that you haven't mistyped your username or password). You can check this using command-line tools like curl or wget (more on that below).
It also makes sense to override the default timeout setting — just in case it's been set too low somewhere in your config files (the system default is 15 seconds). For example:
pip install --proxy http://123.455.234.345:3088 --timeout=60 <package name>
In this example, we’ve set the timeout to 60 seconds.
If the proxy is accessible, but the error only occurs when calling from your Python script, it's likely due to special characters in your username or password.
You need to re-encode special characters. For example:
The most suitable approach is to add the correct security certificates using the --cert=/path/to/certificate/cert.pem option. This error usually occurs when using a third-party package index and authentication falls back to the default SSL (for pypi.org). Naturally, the certificate will be flagged as invalid. You must download and install the SSL certificate for the chosen package index to resolve this.
If you can’t access the correct SSL certificate, you can’t add it — but there’s a workaround.
A temporary workaround is to mark the host address that causes the error as trusted using the --trusted-host flag:
pip install --trusted-host your-index.org --proxy http://123.455.234.345:3088 <package name>
The simplest option is to access the website using the curl utility and print all warnings and information to the console:
curl -I https://pypi.org --proxy http://proxy-user:passwd@proxyserver.com:3038
You may need to download and install the utility manually (from the official curl website) on Windows. Running the script is a bit more complex. First, extract the program into a folder, then navigate to that folder:
cd "C:\path\to\curl\bin\"curl.exe -I https://pypi.org --proxy http://proxy-user:passwd@proxyserver.com:3038
By default, WGET is unavailable in Windows, so it must be downloaded and installed separately.
The syntax for accessing websites through a proxy is as follows:
wget https://pypi.org -e use_proxy=yes -e http_proxy=proxy-user:passwd@proxyserver.com:3038
Alternatively, you can define the proxy at the environment variable level (see the instructions above) and access websites without additional options:
wget https://pypi.org
Standard debugging for the pip package manager is set using the -v parameter. The more v's you add, the more detailed the log output becomes:
Premium mobile IPs for ultimate flexibility and seamless connectivity.
Proxy connection parameters — especially logins and passwords — should be considered sensitive information. Because of this, storing pip proxy credentials directly in your script code is not considered secure. It might be possible in a single-developer scenario (e.g., a personal or fan project), but it's risky in larger teams or when scripts are shared across an organization.
In this case, we recommend defining proxy connection at the environment variable or configuration level (ini/config files).
However, another problem emerges: the more proxies you use in a project, the more complicated it will be to manage them.
An elegant (but paid) solution is available here — using a rotating proxy service like Froxy. You just need to create a separate proxy filter (or a port), grant connection credentials to a user, and then manage the parameters of choosing output addresses via a convenient dashboard. Filters or ports no longer needed are easily disabled and deleted (e.g., if an employee leaves or the proxy for a particular service is obsolete).
Pip is a powerful built-in tool for managing Python libraries. This package manager works with proxies out of the box, adding flexibility and functionality.
Proxies can be configured via CLI, environment variables, or configuration files. A special console utility for pip settings is pip config.
However, it is not enough just to set up pip. You also need quality proxies. You can pick reliable rotating residential, mobile, and server proxies from us. Froxy offers over 10 million IPs from more than 200 countries, targeting cities and mobile operators. Pricing is based on traffic used.