Installation Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide describes the procedures for installing and configuring ProxyBroker2, a production-ready asynchronous proxy management tool. ProxyBroker2 finds, validates, and serves public proxies across HTTP(S) and SOCKS4/5 protocols.
The project requires Python 3.10 or higher. You must install ProxyBroker2 directly from the GitHub repository, as PyPI versions under similar names are unauthorized or abandoned.
Sources: README.md:12-16, README.md:118-120, README.md:130-133
System Requirements
ProxyBroker2 depends on a modern Python environment and specific asynchronous libraries.
| Requirement | Specification |
|---|---|
| Python Version | 3.10, 3.11, 3.12, 3.13, or 3.14 |
| Operating Systems | Linux, macOS, Windows, POSIX |
| Core Dependencies | aiohttp, aiodns, attrs, maxminddb, cachetools, click, pyyaml |
| Build Tools | Poetry (recommended), pip, or uv |
Sources: README.md:118-120, setup.py:38-46, setup.py:65-69, pyproject.toml:42-49
Standard Installation Methods
You can install ProxyBroker2 using pip or uv directly from the source repository.
Using pip
To install the latest version from the default branch, run:
pip install -U git+https://github.com/bluet/proxybroker2.git
Sources: README.md:135-140
Using uv
For projects managed by uv, use the following commands:
# Add to a uv-managed project
uv add "proxybroker2 @ git+https://github.com/bluet/proxybroker2.git%22
# Install into current venv
uv pip install git+https://github.com/bluet/proxybroker2.git
Sources: README.md:149-156
Docker Installation
ProxyBroker2 provides pre-built images via Docker Hub for containerized environments.
The diagram shows the flow from pulling the image to running a container with optional custom provider configurations.
Sources: README.md:110-116, README.md:248-256
Running the Container
- Pull the image:
docker pull bluet/proxybroker2 - View available options:
docker run --rm bluet/proxybroker2 --help - Run with custom providers by mounting a local directory to
/configs:
docker run --rm -v ~/my-proxy-sources:/configs bluet/proxybroker2 find --types HTTP --limit 10
Sources: README.md:112-116, README.md:258-262
Development Setup
The project uses Poetry as its canonical dependency manager for development tasks.
Setup Procedure
- Clone the repository: `git clone https://github.com/bluet/proxybroker2.git%60
- Install dependencies:
poetry install - Activate the environment:
poetry shell - (Optional) Install pre-commit hooks:
pre-commit install
Sources: README.md:364-370, CLAUDE.md:15-18
Build and Test Flow
The following sequence illustrates the typical development setup and verification flow:
Sources: README.md:364-370, CLAUDE.md:21-30
Executable Build (PyInstaller)
You can build a standalone one-file executable for Linux, Windows, or macOS.
Prerequisites
On UNIX-like systems, you must install upx and binutils (providing objdump).
sudo apt install -y upx-ucl binutils
Sources: README.md:162-171
Build Command
Run the following command string to generate the binary in the build/ directory:
pip install pyinstaller && pip install . && \
mkdir -p build && cd build && \
pyinstaller --onefile --name proxybroker --add-data "../proxybroker/data:data" \
--workpath ./tmp --distpath . --clean ../py2exe_entrypoint.py && \
rm -rf tmp *.spec
Sources: README.md:175-181
Migration from Version 0.3.2
Users upgrading from the original, abandoned proxybroker package must take specific steps to ensure compatibility.
- Uninstall the old version:
pip uninstall proxybroker - Update Python: Ensure your environment uses Python 3.10 or higher.
- Change CLI calls: Replace the
proxybrokercommand withpython -m proxybroker. - Update IP representations: Be aware that ProxyBroker2 uses RFC 5952 canonical forms for IPv6 support.
Sources: README.md:323-333, CHANGELOG.md:17-21
ProxyBroker2 modernizes the original codebase by fixing deadlocks, adding first-class IPv6 support, and updating to modern asynchronous Python patterns.
Sources: README.md:41-52, CLAUDE.md:204-210