Skip to content

About

A powerful command-line tool for managing and rotating IP proxies with real-time validation and country-specific filtering.

Topics

Resources

Contributing

Stars

6 stars

Watchers

1 watching

Forks

Latest commit

ย 

History

14 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

Proxy Finder: Free Proxy List Scraper, Proxy Checker & Rotator (Python)

Python License: MIT GitHub stars GitHub issues Sponsor: GeoNode

Proxy Finder is a free, open-source proxy scraper and proxy checker for Python. It collects free proxy lists from 11 public sources (about 125,000 HTTP proxies), checks which proxies actually work, measures their speed, anonymity (elite / anonymous / transparent) and HTTPS support, and returns working proxies by country from about 180 countries. Use it from the command line or as a Python library for proxy rotation in scrapers, bots and tests.

Proxy Finder CLI demo: fetching and validating free proxies by country

pip install git+https://github.com/Abbalochdev/proxy-finder.git
proxy-finder fetch -c US -a elite --https -n 5

Sponsored: need proxies that stay online, or a country free lists can't supply? GeoNode offers residential, ISP and datacenter proxies in 150+ countries with sticky sessions. GeoNode also publishes a free proxy list, which Proxy Finder already uses as a source. Affiliate link: I may earn a commission if you sign up, at no extra cost to you.

Contents

Why Proxy Finder

Most free proxy lists are full of dead, slow or leaky proxies. Proxy Finder does the checking for you:

  • ๐ŸŒ Many sources in one place: GeoNode, ProxyScrape, proxifly, spys.me and 7 popular GitHub proxy lists, downloaded in parallel with retries and a 10-minute cache.
  • โœ… Real proxy checking: a proxy only counts if it actually relays a request and returns the real page. Dead proxies, captive portals and junk responses are rejected.
  • ๐Ÿ•ต๏ธ Anonymity detection: each proxy is tested to see whether it leaks your IP. By default you only get anonymous and elite proxies that hide your real IP address.
  • ๐Ÿ” HTTPS proxy check: tests whether the proxy can tunnel HTTPS (CONNECT) with a valid certificate. Use --https to require it.
  • ๐Ÿ—บ๏ธ Proxies by country: every proxy is placed in a country with an offline IP-geolocation database, so you can search about 180 countries, or several at once (-c US,GB,DE).
  • โšก Fast: 200 checks run in parallel and stop as soon as enough working proxies are found. A typical search takes 4โ€“15 seconds.
  • ๐Ÿ”„ Self-healing proxy rotation: ProxyManager.get_proxy() cycles through validated proxies, drops the ones you report as failed, refills itself, re-validates over time, and is thread-safe.
  • ๐Ÿงน Clean data: duplicates, private IPs and Cloudflare edge IPs (which always reveal your IP) are removed. Proxies listed by several sources are tested first, because they work about twice as often.

Example output

$ proxy-finder fetch -c US -a elite --https -n 5 -s quality
                                        Proxy Results
โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚ IP              โ”‚ Port โ”‚ Country โ”‚ Anonymity โ”‚ Score โ”‚ HTTPS โ”‚ Speed โ”‚ Last Checked        โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚ 209.97.150.167  โ”‚ 3128 โ”‚ US      โ”‚ elite     โ”‚  97.7 โ”‚ yes   โ”‚ 0.46s โ”‚ 2026-11-18 00:13:18 โ”‚
โ”‚ 198.199.86.11   โ”‚ 3128 โ”‚ US      โ”‚ elite     โ”‚  97.7 โ”‚ yes   โ”‚ 0.46s โ”‚ 2026-11-18 00:13:18 โ”‚
โ”‚ 138.68.60.8     โ”‚ 3128 โ”‚ US      โ”‚ elite     โ”‚  96.6 โ”‚ yes   โ”‚ 0.67s โ”‚ 2026-11-18 00:13:19 โ”‚
โ”‚ 216.152.152.44  โ”‚   80 โ”‚ US      โ”‚ elite     โ”‚  93.5 โ”‚ yes   โ”‚ 1.29s โ”‚ 2026-11-18 00:13:20 โ”‚
โ”‚ 216.152.149.246 โ”‚   80 โ”‚ US      โ”‚ elite     โ”‚  91.5 โ”‚ yes   โ”‚ 1.71s โ”‚ 2026-11-18 00:13:25 โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
Checked 504 of 36424 candidates: 89 working, 5 matched your filters.

Installation

Requires Python 3.9+.

# Install straight from GitHub
pip install git+https://github.com/Abbalochdev/proxy-finder.git

# Or from a clone (editable, so local changes take effect immediately)
git clone https://github.com/Abbalochdev/proxy-finder.git
cd proxy-finder
pip install -e .

Without installing, you can also run python run_proxy_finder.py <command> from the repository folder.

On first use, Proxy Finder downloads a free IP-to-country database (~9 MB) to ~/.cache/proxy_finder/.

Usage: get a free proxy list by country

# 5 working proxies that hide your IP, from any country
proxy-finder fetch -n 5

# Free proxy list for one country (two-letter ISO code)
proxy-finder fetch -c US -n 10

# Several countries at once
proxy-finder fetch -c GB,DE,FR,NL -n 10

# Only elite proxies that also support HTTPS
proxy-finder fetch -c DE -a elite --https -n 5

# Accept any working proxy, including transparent ones that reveal your IP
proxy-finder fetch -a transparent -n 5

# Sort by quality score (best overall first), speed (default), country or anonymity
proxy-finder fetch -s quality -n 10

# See how many proxies are listed per country right now
proxy-finder countries

Check if a proxy is working

Use Proxy Finder as a proxy checker for any proxy you already have:

proxy-finder validate 203.0.113.10:8080

It reports whether the proxy works, its speed, anonymity level, HTTPS support and country, and exits with code 1 if the proxy is dead, which makes it handy in scripts. Without an address, validate finds one working proxy for you.

Rotating proxies in Python

import requests
from proxy_finder import ProxyManager

# hides your IP, supports HTTPS, rotates through 3 proxies
manager = ProxyManager(countries=["US", "GB"], https=True, pool_size=3)

for url in ["https://httpbin.org/ip"] * 5:
    proxy = manager.get_proxy()                 # next proxy from a validated pool
    address = f"http://{proxy['proxy']}"
    try:
        r = requests.get(url, proxies={"http": address, "https": address}, timeout=10)
        print(proxy["proxy"], proxy["country"], r.json())
    except requests.RequestException as e:      # free proxies can drop out at any moment
        print(proxy["proxy"], "failed, removing it:", type(e).__name__)
        manager.remove(proxy)                   # never handed out again; pool refills when empty
# Note: requests' timeout is per read, so a stalling free proxy can still hold one request
# for a minute or more. Keep your own time budget if latency matters.

fastest = manager.rotate_proxies(3)             # 3 distinct working proxies, fastest first

How rotation works:

  • get_proxy() cycles through a pool of pool_size validated proxies, round-robin.
  • remove(proxy) drops a proxy that failed for you. When the pool runs empty, the next get_proxy() finds and validates fresh ones, skipping everything you removed.
  • The pool is re-validated every max_age seconds (default 600), because free proxies rarely last long. Pass max_age=None to keep a pool until it empties.
  • One ProxyManager can be shared by many threads. While the pool refills, other threads wait for it instead of each starting its own search.

Each proxy is a dict with proxy (ip:port), country, anonymity, https, speed (seconds), quality_score (0โ€“100), source and last_checked.

Quality score: one number for "how good is this proxy", 0โ€“100. Speed counts 50% (10s or slower earns nothing), validation status 30%, and anonymity 20% (elite > anonymous > transparent). Sort by it with -s quality.

Stricter filters take longer: only about 1 in 300 working free proxies is both elite and HTTPS-capable, so anonymity="elite", https=True can take a minute or more to fill a pool.

Command reference

proxy-finder fetch       Working proxies (count set by -n)
proxy-finder validate    Find one working proxy, or check the IP:PORT you pass
proxy-finder rotate      Up to 5 working proxies to rotate between
proxy-finder countries   Listed proxies per country, right now

-n, --number     Number of proxies (default 5)
-c, --country    Country code, or several: US,GB,DE
-a, --anonymity  Minimum level: transparent (any), anonymous (default), elite
    --https      Only proxies that can tunnel HTTPS
-t, --timeout    Request timeout in seconds (default 6)
-s, --sort       speed (default), quality, country or anonymity

Anonymity levels: transparent proxies pass your real IP to the website; anonymous proxies hide your IP but reveal that a proxy is used; elite (high-anonymity) proxies hide both.

Proxy sources

Source Country data
GeoNode free proxy list from source
ProxyScrape from source
proxifly from source
spys.me from source
GitHub lists: sunny9577, Zaeem20, TheSpeedX, monosans, vakhov, ErcinDedeoglu, MuRongPIG offline geolocation

Sources were picked by measurement: lists that only mirror others, or that are mostly dead, were left out because they slow searches without adding working proxies.

Free vs paid proxies

Free proxies are open, misconfigured or short-lived machines run by strangers. Expect:

  • Usually 1โ€“15% of listed proxies work, and only a small share of those hide your IP.
  • Popular countries are easy (US, DE, GB, FR, NL, SG). Many others, such as Italy or the Gulf states, often have only a handful working at any moment, sometimes none.
  • Proxies disappear within hours, so check again right before use.

For production scraping, a specific country, or stable sessions, a paid provider is the realistic option. GeoNode (sponsor, affiliate link) offers residential, ISP and datacenter proxies in 150+ countries with sticky sessions.

FAQ

How do I get a free proxy list for a specific country? Run proxy-finder fetch -c <CODE>, for example proxy-finder fetch -c JP -n 10. Run proxy-finder countries to see which countries have proxies listed right now.

How do I check if a proxy is working? proxy-finder validate IP:PORT. It sends a real request through the proxy and reports speed, anonymity, HTTPS support and country.

What is the difference between elite, anonymous and transparent proxies? Transparent proxies forward your real IP address. Anonymous proxies hide it but announce that they are proxies. Elite proxies hide both. Proxy Finder measures this for each proxy instead of trusting the list.

Why did my search find nothing? Free proxies in some countries are scarce. The result line (for example "Checked 373 of 376 candidates: 3 working") shows what was found. Try -a transparent, drop --https, add neighbouring countries, or try again later.

Are free proxies safe? Treat them as untrusted. The operator can see and change unencrypted traffic. Only send HTTPS traffic through them (--https finds proxies that support it), and never send passwords or personal data through a free proxy.

Does it support SOCKS proxies? Not yet; Proxy Finder currently finds and checks HTTP/HTTPS proxies.

Can I use it as a library? Yes. from proxy_finder import ProxyManager; see Rotating proxies in Python.

Contributing

Issues and pull requests are welcome. See docs/contributing.md. Good first areas: SOCKS4/5 support, a requests.Session-style helper with automatic proxy failover, new proxy sources (with measured hit rates), and an async validator.

Sponsorship: if Proxy Finder saves you time, or your company wants features prioritized, get in touch at developerno424@gmail.com.

pip install -r requirements-dev.txt
pytest            # offline test suite, network is mocked

Project layout:

src/proxy_finder/
โ”œโ”€โ”€ cli.py              # command-line interface
โ”œโ”€โ”€ exceptions.py
โ””โ”€โ”€ core/
    โ”œโ”€โ”€ fetcher.py      # proxy sources, parsing, caching
    โ”œโ”€โ”€ geo.py          # offline IP-to-country lookup
    โ”œโ”€โ”€ validator.py    # proxy checker: speed, anonymity, HTTPS
    โ””โ”€โ”€ rotation.py     # ProxyManager: fetch + validate + rotate

If Proxy Finder is useful to you, please โญ star the repository; it helps others find it.

License

MIT, see LICENSE.

IP geolocation by DB-IP (IP to Country Lite, CC BY 4.0).

Disclaimer: provided as-is, without warranty. Use proxies only for lawful purposes and respect the terms of the websites you access.

Contact: developerno424@gmail.com ยท GitHub issues

About

A powerful command-line tool for managing and rotating IP proxies with real-time validation and country-specific filtering.

Topics

Resources

Contributing

Stars

6 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages