Python SDK

Install the Python SDK and send your first request through a NodeMaven proxy. The nodemaven package builds proxy settings for Python applications. This guide starts with requests, then shows how to use the same configuration with httpx, aiohttp, and Playwright.

Before you start

You need Python 3.9 or newer, an active Residential/Mobile plan with available traffic, and your proxy credentials. This quickstart uses SDK version 0.1.7.

1. Install the package

Create a virtual environment in your project directory:

python -m venv .venv

Activate it on macOS or Linux:

source .venv/bin/activate

On Windows PowerShell:

.venv\Scripts\Activate.ps1

Install the SDK with the requests extra:

python -m pip install "nodemaven[requests]==0.1.7"

The extra installs requests for the example. The SDK itself does not require it to build proxy settings. If your system uses python3 instead of python, use that command to create the environment.

2. Set your proxy credentials

Open the NodeMaven dashboard and go to Rotating Residential Proxy → Authenticated. Find your credentials under Proxy generator.

Use the base proxy username for your main user or sub-user. Do not pass a generated username that already includes -country-, -sid-, or other settings: the SDK adds those parameters itself. Your dashboard sign-in email and password are different credentials. On macOS or Linux:

export NODEMAVEN_LOGIN='YOUR_PROXY_USERNAME'
export NODEMAVEN_PASSWORD='YOUR_PROXY_PASSWORD'

On Windows PowerShell:

$env:NODEMAVEN_LOGIN = 'YOUR_PROXY_USERNAME'
$env:NODEMAVEN_PASSWORD = 'YOUR_PROXY_PASSWORD'

These variables apply to programs started from the current terminal. A .env file is not loaded automatically by the SDK.

3. Send your first request

Save this as quickstart.py:

import ipaddress

import requests
from nodemaven import Proxy

proxy = Proxy(country="us", filter="medium")

response = requests.get(
    "https://api.ipify.org",
    proxies=proxy.requests(),
    timeout=30,
)
response.raise_for_status()
exit_ip = ipaddress.ip_address(response.text.strip())
print(f"Proxy exit IP: {exit_ip}")

Run it:

python quickstart.py

The output contains the proxy’s public exit IP. For example:

Proxy exit IP: 203.0.113.42

This is illustrative output; your IP will be different. The request uses proxy traffic. If the returned address is your own public IP, check that your client is using the supplied proxy configuration. country="us" selects US exits. filter="medium" explicitly selects the filter used by the dashboard’s Quality mode. Creating the object alone does not send a request or reserve an IP.

Use a different HTTP client

These examples reuse proxy from the quickstart. Install the client you choose inside the same virtual environment.

httpx

Install httpx:

python -m pip install "httpx>=0.28,<0.29"

import httpx

with httpx.Client(proxy=proxy.url(), timeout=30, trust_env=False) as client:
    response = client.get("https://api.ipify.org")
    response.raise_for_status()
    print(response.text.strip())

Use proxy=proxy.url() with this version of httpx. The SDK’s proxy.httpx() helper returns URL strings, not the transport objects expected by httpx’s mounts argument.

aiohttp

Install aiohttp:

python -m pip install aiohttp

import asyncio

import aiohttp

async def fetch_ip():
    timeout = aiohttp.ClientTimeout(total=30)
    async with aiohttp.ClientSession(timeout=timeout) as client:
        async with client.get(
            "https://api.ipify.org", proxy=proxy.url()
        ) as response:
            response.raise_for_status()
            print((await response.text()).strip())

asyncio.run(fetch_ip())

Use Playwright

Install Playwright and its Chromium browser:

python -m pip install playwright
python -m playwright install chromium

Save this as a separate script. It uses a sticky session so the browser can reuse one proxy identity:

from nodemaven import Proxy
from playwright.sync_api import sync_playwright

proxy = Proxy(country="us", filter="medium").session("browser01")

with sync_playwright() as p:
    browser = p.chromium.launch(proxy=proxy.playwright())
    try:
        page = browser.new_page()
        page.goto(
            "https://api.ipify.org",
            wait_until="domcontentloaded",
            timeout=30_000,
        )
        print(page.locator("body").inner_text())
    finally:
        browser.close()

proxy.playwright() returns server, username, and password separately. Pass those fields directly; do not percent-encode them yourself. Browser and HTTP-library requirements can be newer than the SDK’s Python requirement.

Choose the right output

SDK output	Use it for
`proxy.requests()`	The `proxies` argument in `requests`
`proxy.url()`	Clients accepting an authenticated proxy URL
`proxy.playwright()`	Playwright’s `proxy` argument
`proxy.username`	The generated username, including your parameters
`proxy.server`	`host:port` without credentials

URLs and client configuration dictionaries contain the real proxy password. Do not print them to shared logs.

Next steps

Source and issue tracker: nodemaven-python. Package: PyPI.

Get started

Products

More

Before you start

1. Install the package

2. Set your proxy credentials

3. Send your first request

Use a different HTTP client

httpx

aiohttp

Use Playwright

Choose the right output

Next steps

​Before you start

​1. Install the package

​2. Set your proxy credentials

​3. Send your first request

​Use a different HTTP client

​httpx

​aiohttp

​Use Playwright

​Choose the right output

​Next steps

Before you start

1. Install the package

2. Set your proxy credentials

3. Send your first request

Use a different HTTP client

httpx

aiohttp

Use Playwright

Choose the right output

Next steps