ProxyWhirl

Production-grade proxy rotation for Python. 9 intelligent strategies, hundreds of built-in sources, circuit breakers, multi-tier caching, and four interfaces -- all in one library.

Get Started Free Proxy Lists GitHub

ProxyWhirl Documentation

9 Rotation Strategies

Round-robin, random, weighted, least-used, performance-based (EMA), session-persistence, geo-targeted, cost-aware, and composite pipelines.

strategies | Quickstart | Deep dive

Runtime Resilience

Circuit breakers with auto-recovery, retry policies with exponential backoff, EMA latency scoring, multi-tier caching (L1/L2/L3), and proxy lifecycle analytics.

resilience | Caching | Retry & Failover

Four Interfaces

Python sync/async API, REST service (FastAPI + OpenAPI), CLI with 9 commands (Typer), and MCP server for AI assistants.

interfaces | REST | CLI | MCP

Quick Example

Python (sync)

from proxywhirl import ProxyWhirl

rotator = ProxyWhirl(proxies=["http://proxy1:8080", "http://proxy2:8080"])
response = rotator.get("https://httpbin.org/ip")
print(response.json())  # {"origin": "185.x.x.47"}

See Getting Started for full installation and setup.

Python (async)

from proxywhirl import AsyncProxyWhirl

async with AsyncProxyWhirl(proxies=proxies) as rotator:
    response = await rotator.get("https://httpbin.org/ip")
    print(response.json())

See Async Client Guide for connection pooling, error handling, and concurrency patterns.

Auto-Fetch Proxies

from proxywhirl import ProxyFetcher

# Fetch and validate proxies from all built-in sources
fetcher = ProxyFetcher()
proxies = await fetcher.fetch_all(validate=True)
print(f"Found {len(proxies)} working proxies")

See Python API for ProxyFetcher, ProxyValidator, and parser classes.

REST API

# Start the API server
uv run uvicorn proxywhirl.api:app --reload

# Get proxies
curl http://localhost:8000/api/v1/proxies

# Rotate to next proxy
curl -X POST http://localhost:8000/api/v1/rotate

See ProxyWhirl REST API Usage Guide for endpoint reference, authentication, and Docker deployment.

CLI

# Fetch fresh proxies from all built-in sources
proxywhirl fetch --timeout 5

# Validate proxies
proxywhirl validate --protocol http

# Export stats
proxywhirl export --stats-only

See CLI Reference for all 9 commands, global options, and output formats.

MCP Server

# Run the MCP server for AI assistants
uv run proxywhirl mcp --transport stdio

# Or with uvx (no install needed)
uvx proxywhirl mcp

See MCP Server Guide for tool definitions, auto-loading, and Claude/GPT integration.

Rotation Strategies at a Glance

All 9 strategies implement the RotationStrategy protocol and can be hot-swapped at runtime via StrategyRegistry.

Strategy	Class	Best For
Round-Robin	RoundRobinStrategy	Even distribution across all proxies
Random	RandomStrategy	Unpredictable rotation patterns
Weighted	WeightedStrategy	Favoring reliable proxies by success rate or custom weights
Least-Used	LeastUsedStrategy	Load balancing (min-heap, O(log n) selection)
Performance-Based	PerformanceBasedStrategy	Lowest latency (EMA scoring with cold-start exploration)
Session Persistence	SessionPersistenceStrategy	Sticky sessions with TTL expiration and LRU eviction
Geo-Targeted	GeoTargetedStrategy	Region-aware routing by country/region codes
Cost-Aware	CostAwareStrategy	Budget optimization (free proxies boosted 10x)
Composite	CompositeStrategy	Chaining filters + selectors (e.g., geo-filter then performance-select)

Strategy overview | Advanced strategies guide | Python API reference

Documentation Sections

Getting Started

Installation, quickstart examples, and your first rotating proxy setup.

• Installation & quickstart

• Rotation strategies overview

• Sync vs async decision guide

• Using free proxy lists

Getting Started

Guides

Deep dives: async patterns, advanced strategies, caching, retry/failover, CLI, and MCP server.

• Async client patterns – connection pools, error handling

• Advanced strategies – EMA scoring, geo-routing, composites

• Retry & failover – circuit breakers, backoff policies

• Deployment security – Nginx, Caddy, HAProxy configs

Guides

Concepts

Design philosophy: why things work the way they do.

• Rotation strategies – Protocol pattern, registry, composition

• Cache architecture – L1/L2/L3 tiers, promotion/demotion

• Circuit breakers – failure isolation, automatic recovery

• Security model – encryption, redaction, SSRF protection

Concepts

API Reference

REST API, Python API, configuration, exceptions, caching, and rate limiting.

• REST API endpoints – OpenAPI, auth, Docker

• Python API – rotators, strategies, fetchers, validators

• Configuration reference – TOML, env vars, discovery

• Exception hierarchy – error codes, URL redaction

Reference

Project

Contributing, development setup, CI/CD, changelog, and project status.

• Development environment setup

• Contributing guidelines

• CI/CD pipelines

• Architecture overview

Project

What’s New

• Composite Strategies – chain filters and selectors with <5 us overhead via CompositeStrategy

• Cost-Aware Strategy – budget-optimize proxy selection with CostAwareStrategy

• MCP Server – Model Context Protocol integration for Claude, GPT, and more

• Free Proxy Lists – updated every 6 hours from hundreds of sources at proxywhirl.com

• Rate Limiting – token bucket algorithm with per-proxy and global limits via Rate Limiting API Reference

Looking for proxy lists?

Visit the ProxyWhirl Dashboard to browse, filter, and download free proxy lists updated every 6 hours. Or fetch them programmatically: await ProxyFetcher().fetch_all(validate=True)