INTEGRACIONES

Cómo usar un proxy con Python requests

Dirige requests a una dirección ISP estática: una sola IP en la red de un proveedor de internet con nombre, conservada durante el periodo que pagas. El código de abajo se ejecutó contra un proxy con autenticación antes de publicarse.

Ver el catálogo Todas las integraciones

En resumen: Pasa un diccionario proxies con las claves http y https, cada una con el valor http://USERNAME:PASSWORD@HOST:PORT, y requests envía la llamada a través del proxy; los destinos HTTPS lo atraviesan como túnel. Para SOCKS5, instala requests[socks], cambia el proxy a SOCKS5 en tu pedido y usa el esquema socks5h, para que sea el proxy, y no tu máquina, quien resuelva los nombres de host.

Python requests toma su proxy de un diccionario que asocia el esquema de la URL de destino con una URL de proxy. Esta guía configura ese diccionario para una dirección ISP estática y muestra los tres sitios donde puede estar: en una llamada, en una sesión o en el entorno.

Proxy en Python requests con usuario y contraseña

La mayoría de los proxies, los nuestros incluidos, piden usuario y contraseña. requests los lee de la URL del proxy y se los envía al proxy en cada conexión. Para un destino HTTPS, el proxy abre un túnel y nunca ve el contenido de la solicitud. Las pestañas de código muestran la forma por solicitud y la de sesión.

PASO A PASO

Configurar un proxy en Python requests

Copia los cuatro valores de tu pedido
Host, puerto, usuario y contraseña, desde Mis Proxies en el panel o desde el pedido en la API. Cada dirección tiene sus propios cuatro valores; no hay una pasarela compartida.
Construye una URL de proxy
http://USERNAME:PASSWORD@HOST:PORT. Si la contraseña contiene /, ?, # o %, aplícale antes la codificación URL con urllib.parse.quote(password, safe="").
Asígnala a los dos esquemas
Da la misma URL a la clave http y a la clave https. Si solo está http, todas las solicitudes HTTPS se saltan el proxy y salen desde tu propia dirección.
Comprueba una vez la dirección de salida
Solicita una página que muestre la IP de quien llama, o abre Cuál es mi IP a través del mismo proxy, y confirma que es la dirección que compraste.
Ejecuta el trabajo con un timeout
Pasa siempre timeout=: por defecto requests espera indefinidamente, y una conexión atascada parece entonces un script colgado.

Por solicitud Sesión SOCKS5

import requests

# The four values come with your order (dashboard or API)
proxy = "http://USERNAME:PASSWORD@HOST:PORT"

response = requests.get(
    "https://example.com/",
    proxies={"http": proxy, "https": proxy},
    timeout=30,
)
response.raise_for_status()
print(response.status_code)

import requests

proxy = "http://USERNAME:PASSWORD@HOST:PORT"

with requests.Session() as session:
    # HTTP_PROXY / HTTPS_PROXY in the environment would override
    # session.proxies; this makes the session use only its own setting.
    session.trust_env = False
    session.proxies.update({"http": proxy, "https": proxy})
    response = session.get("https://example.com/", timeout=30)
    response.raise_for_status()
    print(response.status_code)

# pip install "requests[socks]"
import requests

# Switch the proxy to SOCKS5 first; use the values the order then shows.
# socks5h: the proxy resolves the hostname, not your machine.
proxy = "socks5h://USERNAME:PASSWORD@HOST:PORT"

response = requests.get(
    "https://example.com/",
    proxies={"http": proxy, "https": proxy},
    timeout=30,
)
response.raise_for_status()
print(response.status_code)

CÓDIGO

Código probado para requests

Cada ejemplo se conecta a través de un proxy HTTP con usuario y contraseña, salvo el de SOCKS5, que necesita el proxy cambiado antes a SOCKS5; el pedido muestra entonces un puerto nuevo y credenciales nuevas que debes usar. Sustituye los cuatro valores en mayúsculas por los de tu pedido.

Documentación completa de la API

Por solicitud Pasa el proxy a una sola llamada. Sesión Configura el proxy una vez para todas las llamadas de una sesión. SOCKS5 SOCKS5 con los nombres de host resueltos en el proxy.

OPCIONES

Dónde se puede configurar el proxy en requests

Tomado de la documentación de requests y comprobado con los ejemplos de código de esta página contra un proxy local con autenticación. Cuando hay más de uno configurado, un argumento proxies en la llamada se impone al entorno, y el entorno se impone a Session.proxies salvo que la sesión ponga trust_env en False, como hace el ejemplo de sesión.
	Alcance	Credenciales	Cuándo usarlo
proxies= en una llamada	Esa única solicitud	En la URL	Un script con unas pocas llamadas
Session.proxies	Todas las solicitudes de la sesión	En la URL	Cualquier cosa más larga, con trust_env en False
HTTP_PROXY y HTTPS_PROXY	Todas las llamadas de requests del proceso	En la URL	Código que no puedes editar; NO_PROXY enumera los hosts que se omiten
URL socks5h://	El alcance en el que se configure	En la URL	Cuando los nombres de host deben resolverse en el proxy

ERRORES FRECUENTES

Qué sale mal con requests y los proxies

Solo está la clave http

La clave indica el esquema del destino, no el del proxy. Un diccionario con solo http enruta el HTTP sin cifrar y deja que todas las llamadas HTTPS salgan directamente, sin ningún error que te avise.

socks5 donde se quería socks5h

Con socks5, tu máquina resuelve el nombre de host y entrega al proxy una IP. Con socks5h lo resuelve el proxy, así que la consulta y su respuesta vienen de la red del proxy, lo que importa en los sitios que responden según la ubicación.

Una contraseña que rompe la URL

Una barra, un signo de interrogación o una almohadilla en la contraseña cortan la URL, y requests falla antes de llegar al proxy; un signo de porcentaje se interpreta como secuencia de escape. Aplica a la contraseña la codificación URL, o usa la autenticación por lista blanca de IP y deja fuera las credenciales.

Una variable de entorno olvidada

requests lee HTTP_PROXY, HTTPS_PROXY y NO_PROXY salvo que pongas trust_env en False en la sesión, y esas variables se imponen a Session.proxies. Una variable antigua en un servidor puede mandar el tráfico de una sesión a un sitio que no pretendías, o hacer que rodee el proxy.

LA DIRECCIÓN

A qué se conecta requests

Protocolos: HTTP, que transporta HTTPS, o SOCKS5, que se activa en el pedido
Autenticación: Usuario y contraseña, o una lista blanca de IP establecida a través de la API
Dirección: Una IP estática durante el periodo, en la red de un proveedor de internet con nombre
Rotación: Ninguna: la misma dirección en cada solicitud

RELACIONADO

Otras guías y el producto

Selenium Un proxy para un navegador controlado por Selenium

Playwright Un proxy por navegador o por contexto

Proxies SOCKS5 El protocolo, y cómo cambiar a él

Proxies ISP Las direcciones estáticas que usan estas guías

FAQ

Preguntas sobre proxies en Python requests

¿Cómo uso un proxy con autenticación en Python requests?

Pon el usuario y la contraseña en la URL del proxy, http://USERNAME:PASSWORD@HOST:PORT, y pásala para las claves http y https. requests envía las credenciales al proxy, que responde 407 si son incorrectas. Codifica una contraseña que contenga caracteres reservados, o usa una lista blanca de IP en su lugar.

¿Cómo uso un proxy SOCKS5 con requests?

Instala el extra con pip install requests[socks], cambia el propio proxy a SOCKS5 en tu pedido y usa el puerto y las credenciales que el pedido muestra entonces en una URL socks5h://. Cambiar solo el esquema no basta: una dirección configurada en HTTP no responde por SOCKS5 hasta que se cambia. SOCKS5

¿Puedo usar autenticación por lista blanca de IP en lugar de una contraseña?

Sí. Añade la dirección IPv4 pública desde la que se ejecuta tu script a la lista blanca del proxy con una llamada a la API, PUT /orders/ORDER_ID/whitelist, o a través del servidor MCP; el panel todavía no tiene ningún control para ello. El proxy acepta entonces conexiones desde esa dirección sin credenciales, por HTTP y por SOCKS5, y la URL pasa a ser http://HOST:PORT. Mientras hay una lista blanca establecida, el proxy solo admite las direcciones de la lista y el usuario y la contraseña dejan de funcionar para ese pedido; si envías una lista vacía, la lista blanca se desactiva y el inicio de sesión con contraseña vuelve a funcionar.

¿La dirección rota entre solicitudes?

No. Un proxy ISP estático es una sola dirección durante el periodo que pagas, y todas las solicitudes que envías a través de él salen desde esa dirección. Si un trabajo necesita una dirección distinta por solicitud, eso es un pool rotativo, que todavía no vendemos.

¿Cómo compruebo qué IP ve un sitio?

Solicita a través del mismo proxy una página que devuelva la dirección de quien llama, o abre Cuál es mi IP desde un navegador configurado con él. Si muestra tu propia dirección, probablemente falta la clave https. Cuál es mi IP

¿Para qué puedo usar el proxy?

Las pruebas de tus propios sitios por región, los controles de calidad, la verificación de anuncios, la investigación de precios y de mercado y la protección de marca no necesitan revisión según nuestra política de uso aceptable. El proxy no sortea CAPTCHAs, detección de bots, límites de frecuencia ni bloqueos de cuentas, y la política prohíbe usarlo para intentarlo. Política de Uso Aceptable

Una dirección estática encaja con los trabajos que deben llegar cada vez desde el mismo sitio: un monitor, una comprobación regional, una prueba que compara hoy con la semana pasada. Pide una dirección por trabajo en la página de proxies ISP, consulta la página de precios y, si el mismo trabajo se ejecuta en un navegador, las guías de Selenium y Playwright configuran allí la misma dirección.

Fuentes

Requests documentation, Proxies: el argumento proxies, las variables de entorno y la compatibilidad con SOCKS
RFC 1928, SOCKS Protocol Version 5: cómo pide un cliente a un proxy SOCKS5 un destino por nombre o por dirección
RFC 3986, URI Generic Syntax: la parte userinfo de una URL y los caracteres que deben codificarse en ella