> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nodemaven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Install the Python SDK and send your first proxy request with requests, httpx, aiohttp, or Playwright.

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:

```bash theme={null}
python -m venv .venv
```

Activate it on macOS or Linux:

```bash theme={null}
source .venv/bin/activate
```

On Windows PowerShell:

```powershell theme={null}
.venv\Scripts\Activate.ps1
```

Install the SDK with the `requests` extra:

```bash theme={null}
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](https://dashboard.nodemaven.com) and go to **Rotating Residential Proxy → Authenticated**. Find your credentials under **Proxy generator**.

![Proxy Setup 1](https://mintcdn.com/node-maven/l_oWfdd8xhVH5Vk9/images/proxy-setup-1.png?fit=max\&auto=format\&n=l_oWfdd8xhVH5Vk9\&q=85\&s=ea4b231d7d531cdff12b16422e44aea9)

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:

```bash theme={null}
export NODEMAVEN_LOGIN='YOUR_PROXY_USERNAME'
export NODEMAVEN_PASSWORD='YOUR_PROXY_PASSWORD'
```

On Windows PowerShell:

```powershell theme={null}
$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`:

```python theme={null}
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:

```bash theme={null}
python quickstart.py
```

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

```text theme={null}
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`:

```bash theme={null}
python -m pip install "httpx>=0.28,<0.29"
```

```python theme={null}
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`:

```bash theme={null}
python -m pip install aiohttp
```

```python theme={null}
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:

```bash theme={null}
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:

```python theme={null}
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

* [Configure location, pool, and filters](https://docs.nodemaven.com/developer-sdks/configuration.md)
* [Keep a session or create identities for workers](https://docs.nodemaven.com/developer-sdks/sessions.md)
* [Check connections and handle errors](https://docs.nodemaven.com/developer-sdks/connection-checks.md)
* [Use the account API](https://docs.nodemaven.com/developer-sdks/account-api.md)

Source and issue tracker: [nodemaven-python](https://github.com/nodemaven/nodemaven-python). Package: [PyPI](https://pypi.org/project/nodemaven/).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.