# Configure a proxy in Python Requests

Source: https://ipvolt.com/guides/python-requests-proxy
Markdown: https://ipvolt.com/guides/python-requests-proxy.md

[Home](https://ipvolt.com/index.md) / [Guides](https://ipvolt.com/guides.md) / [Configure a proxy in Python Requests](https://ipvolt.com/guides/python-requests-proxy.md)

Category: Integration
Reviewed: 2026-09-10
Reading time: 4 minutes
Author: ipvolt

Make a Python Requests proxy configuration explicit, encode credentials correctly, and distinguish connect and read timeouts from a total job deadline.

## The starting point

A small, explicit Requests configuration makes proxy selection and authentication easier to reproduce across development and production.

## Prepare an explicit configuration

Install Requests with python -m pip install requests in your project's virtual environment. Inject PROXY_USERNAME and PROXY_PASSWORD privately. Set PROXY_URL to the provider's gateway, including its scheme and port; https://proxy.example.invalid:8443 is only a nonworking illustration.

The dictionary keys below select the destination scheme. Both keys may point at the same gateway. Pass the dictionary on the request instead of relying on a workstation's inherited proxy settings.


## Encode credentials and bound network waits

Save as proxy_check.py and run python proxy_check.py. Encode the username and password individually so characters such as @ or / cannot change the URL structure. Keep the original proxy URL free of credentials.

### proxy_check.py · Python 3 + Requests

```python
import os
from urllib.parse import quote, urlsplit, urlunsplit
import requests

gateway = urlsplit(os.environ["PROXY_URL"])
if gateway.scheme not in {"http", "https"} or not gateway.hostname:
    raise ValueError("Use your provider's HTTP(S) proxy URL")
if gateway.username is not None or gateway.path not in {"", "/"} or gateway.query or gateway.fragment:
    raise ValueError("Keep credentials and paths out of PROXY_URL")
username = quote(os.environ["PROXY_USERNAME"], safe="")
password = quote(os.environ["PROXY_PASSWORD"], safe="")
proxy = urlunsplit((gateway.scheme, f"{username}:{password}@{gateway.netloc}", "", "", ""))

with requests.Session() as session:
    session.trust_env = False
    with session.get(
        "https://example.com/",
        proxies={"http": proxy, "https": proxy},
        timeout=(10, 20),
        allow_redirects=False,
        stream=True,
    ) as response:
        response.raise_for_status()
        print({"status": response.status_code})
```


## Know what the timeout measures

The tuple supplies separate connect and read timeouts. A read timeout limits waiting for socket data; it is not a total download deadline. Apply a separate wall-clock budget in your job runner when a whole task must finish by a fixed time. This diagnostic streams and closes the response without downloading the full body.

Setting trust_env to False also disables Requests' environment-derived authentication and CA-bundle settings. If your organization uses a custom trust bundle, pass its approved file explicitly with verify. Do not use verify=False to make a failing test pass.


## Make failures comparable

Run the same gateway and destination in curl before adding retry logic. Record exception class, attempt number and elapsed time, with credentials removed. A reproducible authentication error needs a configuration change; repeating it at higher concurrency adds noise.

- SOCKS is optional: install requests[socks] and use the matching SOCKS URL in a separate configuration.
- For SOCKS, socks5h delegates destination DNS to the proxy; socks5 resolves locally.
- A successful HTTP request alone does not verify the exit's location.


## Before you ship

- Use a project virtual environment.
- Encode credentials separately from the gateway.
- Keep a job deadline in addition to network timeouts.

## Sources & further reading

- [Requests: proxies, environment configuration and SOCKS](https://requests.readthedocs.io/en/latest/user/advanced/#proxies)
- [Requests: timeouts and errors](https://requests.readthedocs.io/en/latest/user/quickstart/#timeouts)
- [Python: URL parsing and quoting](https://docs.python.org/3/library/urllib.parse.html)

## Related guides

- [Use a proxy with curl](https://ipvolt.com/guides/curl-proxy-setup.md)
- [Proxy environment variables: HTTP_PROXY and NO_PROXY](https://ipvolt.com/guides/proxy-environment-variables.md)
- [Troubleshoot proxy timeouts one stage at a time](https://ipvolt.com/guides/proxy-timeout-troubleshooting.md)

## About ipvolt

Examples use generic proxy settings, with links to the original technical documentation. Product-specific behavior must be checked with your provider. ipvolt is still in development.

## Know when access opens.

ipvolt · In development

We’re building proxy infrastructure for developers and data teams. Join the interest list for a heads-up when ipvolt is ready.

Consent: One email when access opens. Nothing else.

[Get early access](https://ipvolt.com/guides/python-requests-proxy#waitlist-closing). Use the email form on this page to join the interest list.

[Privacy](https://ipvolt.com/privacy)