Install ProxyWhirl, drop in a rotator, auto-fetch proxies, and make the first request.

Quickstart

Install ProxyWhirl with uv first:

# Install uv first if needed
brew install uv
# Other platforms: https://docs.astral.sh/uv/getting-started/installation/

# Add ProxyWhirl to the current project
uv add proxywhirl

# Run the CLI once without adding it to the project
uvx proxywhirl --help

# Install the CLI as a persistent user tool
uv tool install proxywhirl

Use uv run proxywhirl --help inside a uv-managed project. Use uv tool install proxywhirl when you want the CLI available from any shell.

Install optional features with uv extras:

uv add "proxywhirl[storage]"   # SQLite persistence
uv add "proxywhirl[security]"  # Credential encryption
uv add "proxywhirl[js]"        # JS-rendered proxy sources
uv add "proxywhirl[mcp]"       # MCP server for AI assistants

Drop in a rotator and let ProxyWhirl fetch its own proxies on first use:

from proxywhirl import ProxyWhirl

# The empty pool is lazily hydrated from every enabled built-in public source.
rotator = ProxyWhirl()
response = rotator.get("https://httpbin.org/ip")
print(response.json())

Pass explicit proxies only when you want to bring your own pool:

from proxywhirl import ProxyWhirl

rotator = ProxyWhirl(proxies=["http://p1:8080", "http://p2:8080"])
response = rotator.get("https://httpbin.org/ip")

Check the CLI from the same environment:

uv run proxywhirl sources
uv run proxywhirl sources --validate --fail-on-unhealthy --timeout 5 --concurrency 5
uv run proxywhirl fetch --no-save-db --no-export --timeout 5 --concurrency 20
uv run proxywhirl fetch
uv run proxywhirl pool list
uv run proxywhirl health

Use fetch --no-save-db --no-export for a non-mutating network smoke. Use the strict sources --validate command before depending on the built-in public source catalog in production.

Use the async client when your application is already async or needs high concurrency:

import asyncio

from proxywhirl import AsyncProxyWhirl


async def main() -> None:
    async with AsyncProxyWhirl() as rotator:
        response = await rotator.get("https://httpbin.org/ip")
        print(response.json())


asyncio.run(main())

What To Read Next

Need	Destination
Choose a rotation policy	Strategy Matrix
Configure API or service mode	REST/OpenAPI
Use the terminal	CLI Reference
Connect AI assistants	MCP Server

Quickstart

Quickstart

What To Read Next

On this page