Migration from ProxyBroker v0.3.2
Relevant source files
The following files were used as context for generating this wiki page:
ProxyBroker2 serves as the actively-maintained successor to the original ProxyBroker (v0.3.2), which was abandoned in 2018. This page details the necessary steps and changes required to transition from the legacy version to the modernized ProxyBroker2.
The project modernizes the stack by adding first-class IPv6 support, updated asynchronous patterns, and a custom provider system while maintaining high compatibility with the original Python API.
Sources: README.md:14-17, README.md:468-472, CLAUDE.md:155-159
Breaking Changes
Migration requires addressing several breaking changes related to environment requirements, installation methods, and command-line execution.
Environment and Installation
ProxyBroker2 requires Python 3.10 or higher. The original v0.3.2 supported Python 3.5.3+. Additionally, the installation source has changed because the original PyPI names are either abandoned or squatted by unauthorized publishers.
| Feature | ProxyBroker v0.3.2 | ProxyBroker2 (v2.0.0+) |
|---|---|---|
| Python Version | 3.5.3+ | 3.10 to 3.14 |
| Install Source | pip install proxybroker | `pip install git+https://github.com/bluet/proxybroker2.git%60 |
| CLI Command | proxybroker <command> | python -m proxybroker <command> |
Sources: README.md:107-112, README.md:477-495, CHANGELOG.md:162-164, setup.py:65
Deprecated and Removed Features
- GeoIP Updates: The
update-geocommand andupdate_geoip_db()function are broken. MaxMind retired the unauthenticated endpoint in 2019. The function now raises aRuntimeError. - Legacy Asyncio: Deprecated patterns such as
asyncio.ensure_future()are replaced withasyncio.create_task().
Sources: CHANGELOG.md:113-125, CHANGELOG.md:169-170
New Capabilities and Features
ProxyBroker2 introduces features that were absent in v0.3.2, primarily focused on modern network protocols and extensibility.
First-Class IPv6 Support
Unlike the IPv4-only v0.3.2, ProxyBroker2 implements full IPv6 support across detection, validation, and proxying. It uses RFC 5952 canonical forms for IP representation.
The diagram shows how both IPv4 and IPv6 inputs are normalized to a canonical form before performing anonymity validation via set membership.
Sources: CHANGELOG.md:13-35, CLAUDE.md:83-99
Custom Proxy Providers
ProxyBroker2 allows users to add proxy sources without modifying the core codebase. You can drop YAML or JSON configuration files into a specific directory, which the broker loads at startup.
Sources: README.md:195-214, CHANGELOG.md:73-86, CLAUDE.md:133-146
API Compatibility
The core Python API remains largely compatible with v0.3.2, allowing most legacy scripts to function with minimal changes.
# This pattern remains valid in ProxyBroker2
import asyncio
from proxybroker import Broker
async def main():
proxies = asyncio.Queue()
broker = Broker(proxies)
await broker.find(types=['HTTP'], limit=10)
if __name__ == "__main__":
asyncio.run(main()) # Recommended modern entry point
Sources: README.md:175-190, README.md:500-512
Functional Transitions
- Broker Initialization:
Broker()now handles signal cleanup internally to prevent memory leaks found in the original version. - ProxyPool: Now uses a min-heap priority queue based on
proxy.avg_resp_time(formerlypriorityin some internal legacy contexts). - Deterministic Protocols: Protocol selection follows a strict priority: SOCKS5 → SOCKS4 → CONNECT:80 → CONNECT:25 → HTTPS → HTTP.
Sources: CLAUDE.md:61-81, CHANGELOG.md:165-172
Summary of Architectural Improvements
ProxyBroker2 resolves critical issues present in the v0.3.2 release to ensure production readiness.
| Improvement | Description |
|---|---|
| Bug Fixes | Resolved deadlocks, memory leaks, and signal handler leaks. |
| Testing | Shifted to contract-based testing to protect user-visible behavior. |
| Dependencies | Updated to modern versions of aiohttp, aiodns, and attrs. |
| Concurrency | Implemented modern asyncio.run and get_running_loop patterns. |
Sources: README.md:31-42, CLAUDE.md:148-153, CHANGELOG.md:148-160