How to Use Geonode Proxies with Python

Setup

Generate an endpoint in the Geonode dashboard (product, rotating or sticky session, location, host:port:username:password format) and export the values:

export GEONODE_HOST="<host>"
export GEONODE_PORT="<port>"
export GEONODE_USER="<username>"
export GEONODE_PASS="<password>"

Keep credentials out of code and out of version control. A small helper builds proxy URLs everywhere else:

import os
from urllib.parse import quote

def geonode_url(country=None, scheme="http"):
    user = os.environ["GEONODE_USER"] + (f"-country-{country}" if country else "")
    pw = quote(os.environ["GEONODE_PASS"], safe="")
    return f"{scheme}://{user}:{pw}@{os.environ['GEONODE_HOST']}:{os.environ['GEONODE_PORT']}"

The -country- suffix follows the pattern in Geonode's documentation (for example -country-jp); use your dashboard's exact format. URL-encoding the password avoids errors when it contains characters such as @ or :.

requests

import requests

proxy = geonode_url("us")
r = requests.get("https://api.ipify.org", proxies={"http": proxy, "https": proxy}, timeout=30)
print(r.text)

For several requests that should share cookies and an IP (with a sticky endpoint), use a Session:

s = requests.Session()
s.proxies = {"http": proxy, "https": proxy}
s.get("https://example.com/", timeout=30)
s.get("https://example.com/page/2", timeout=30)

See Python requests proxies.

httpx

import httpx

with httpx.Client(proxy=geonode_url("gb"), timeout=30) as client:
    print(client.get("https://api.ipify.org").text)

httpx also supports HTTP/2 and async clients with the same proxy option.

aiohttp for concurrency

import asyncio
import aiohttp

async def fetch(session, url, sem):
    async with sem:
        async with session.get(url, proxy=geonode_url("us"), timeout=aiohttp.ClientTimeout(total=30)) as r:
            return r.status, await r.text()

async def main(urls):
    sem = asyncio.Semaphore(20)
    async with aiohttp.ClientSession() as session:
        return await asyncio.gather(*(fetch(session, u, sem) for u in urls), return_exceptions=True)

Cap concurrency per target domain to stay polite and avoid blocks.

SOCKS5

Geonode lists SOCKS5 support for residential proxies. With requests, install the SOCKS extra (pip install "requests[socks]") and use the socks5h scheme so DNS is resolved through the proxy:

proxy = geonode_url("de", scheme="socks5h")
requests.get("https://api.ipify.org", proxies={"http": proxy, "https": proxy}, timeout=30)

SOCKS5 may use a different port from HTTP; check the dashboard. See SOCKS5 proxies.

Retries and block detection

Check for real content, not just status 200, and retry with a new IP:

import time

def get_with_retry(url, marker, attempts=3):
    for n in range(attempts):
        p = geonode_url("us")
        try:
            r = requests.get(url, proxies={"http": p, "https": p}, timeout=30)
            if r.ok and marker in r.text:
                return r
        except requests.RequestException:
            pass
        time.sleep(1 + n * 2)
    return None

With a rotating endpoint, each new connection gets a new exit. Disable connection reuse (use fresh requests rather than one session) when you want a new IP per attempt.

Common errors

See common proxy errors.

Picking a Geonode product for your Python job

The Python examples above work with any Geonode product; only the endpoint changes. Choose based on the target and the shape of the job.

Many Python projects route by domain: a dictionary mapping domains to "datacenter" or "residential", consulted by the helper that builds proxy URLs. Start every new domain on datacenter, measure success on real content, and promote it to residential only if it fails. That habit keeps per-GB costs low.

A checklist for Python proxy code in production

• Timeouts on every request. Without them, a stalled exit can hang a worker indefinitely.
• Retries with a fresh IP and backoff, capped at two or three attempts.
• Content checks to catch block pages that return status 200.
• Per-domain concurrency limits, especially with aiohttp or httpx async clients, which make it easy to send far more requests than a site tolerates.
• Connection reuse on purpose: reuse a Session for sticky flows, avoid it when you want a new exit per request.
• Secrets outside the code, loaded from environment variables or a secrets manager.
• Structured logs with domain, outcome, status, latency and bytes, so you can see success rates and bandwidth per target.
• A smoke test that requests an IP echo endpoint through each configured product at startup and fails fast if credentials are wrong.

For framework-level crawling with built-in throttling and retries, see Geonode with Scrapy. For a wider view of scraping with Geonode, see Geonode for web scraping.

Testing your setup

A quick self-test catches most configuration mistakes before they reach production:

1. Request an IP echo service three times through a rotating endpoint; expect three different IPs.
2. Request it three times through a sticky endpoint with a Session; expect the same IP.
3. Request a geolocation service through a country-targeted endpoint; expect the right country.
4. Request your real target once and check for expected content.

Wrap these in a small script that exits with an error if any check fails, and run it at deploy time and in CI with a test sub-user. When something breaks later, run the same script first: it tells you within seconds whether the problem is credentials, targeting, sessions or the target itself. For command-line checks, see Geonode with cURL.

To compare Geonode with other providers for Python scraping, see our guide to the best proxies in 2026.

Comparing two popular self-serve providers? Webshare vs Geonode for Python breaks down which fits this job and when it makes sense to use both.

Considering Rayobyte instead of, or alongside, Geonode for this? Rayobyte vs Geonode for Python compares the two, and Using Rayobyte Proxies With Python covers the Rayobyte setup.

FAQ

How do I rotate IPs with requests?

Use a rotating Geonode endpoint and new connections per request. A shared Session reuses connections and may keep the same exit.

How do I keep the same IP across requests?

Use a sticky endpoint and a Session.

Why does my password break the proxy URL?

Special characters must be URL-encoded. Use urllib.parse.quote.

Which library should I use?

requests for simple scripts, httpx for modern sync or async code with HTTP/2, aiohttp for high-concurrency async jobs.

Sources and further reading

Independent references that back up the points above, from standards bodies, governments, universities and non-profits. They open in a new tab.

• SP 800-63B: Authentication and Authenticator Management (NIST): NIST's guidance on passwords and authentication, relevant to proxy credentials and accounts.
• RFC 1928: SOCKS Protocol Version 5 (IETF / RFC Editor): The original specification of SOCKS5, including UDP support and authentication negotiation.
• urllib.request documentation (Python Software Foundation): Python's standard library documentation, including ProxyHandler.
• RFC 7617: The Basic HTTP Authentication Scheme (IETF / RFC Editor): The scheme most proxy providers use for username and password authentication.
• RFC 1929: Username/Password Authentication for SOCKS V5 (IETF / RFC Editor): How SOCKS5 proxies check a username and password.