Intelligent proxy rotation that just works

Docs
  
Examples
  
Discussions

---

30-Second Setup

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

# Add ProxyWhirl to a uv-managed project
uv add proxywhirl

# Or try the CLI without installing it first
uvx proxywhirl --help

Prefer uv tool install proxywhirl when you want the proxywhirl CLI available globally.

from proxywhirl import ProxyWhirl

# Drop it in as your HTTP client; the first request fetches across all enabled
# built-in public sources, validates the results, and keeps the pool in memory.
rotator = ProxyWhirl()
response = rotator.get("https://api.example.com/data")
# Dead proxies are ejected, slow ones are deprioritized, and fast ones are favored.

---

Why ProxyWhirl?

9 Strategies Round-robin, weighted, geo-targeted, performance-based & more

88 Sources Auto-fetch from built-in providers with validation

Self-Healing Auto-eject dead proxies, circuit breakers, recovery

Blazing Fast Async-first, <3μs selection, zero blocking

---

Rotation Strategies

# Switch strategies on the fly
rotator = ProxyWhirl(strategy="performance-based")
rotator.set_strategy("geo-targeted", preferences={"US": [...], "EU": [...]})

Strategy	Best For
round-robin	Even distribution
random	Unpredictable patterns
weighted	Favor reliable proxies
least-used	Even load balance
performance-based	Lowest latency
geo-targeted	Regional routing
session-persistence	Sticky sessions
cost-aware	Budget optimization
composite	Custom pipelines

---

Auto-Fetch Proxies

from proxywhirl import BootstrapConfig, ProxyWhirl

# Default: lazy auto-fetch from every enabled built-in source when the pool is empty.
rotator = ProxyWhirl()
response = rotator.get("https://api.example.com/data")

# Tune bootstrap behavior when you want lighter startup or tighter caps.
rotator = ProxyWhirl(bootstrap=BootstrapConfig(sample_size=20, max_proxies=200))

---

Multiple Interfaces

Python API rotator.get(url) rotator.post(url, json=data) async with AsyncProxyWhirl() as async_rotator: await async_rotator.get(url)

CLI uvx proxywhirl fetch uvx proxywhirl sources --validate --fail-on-unhealthy --timeout 5 --concurrency 5 uv run proxywhirl pool list proxywhirl health # after `uv tool install proxywhirl`

REST API docker-compose up -d curl localhost:8000/api/proxies

---

Learn More

  Full Documentation  
   
  Strategy Matrix  
   
  MCP Server  
   
  Examples  

---

GitHub · Issues · MIT License

_{Built with ❤️ for ethical web automation}