# freeproxy: harvesting and verifying free proxy lists from dozens of public sources

> freeproxy is a Python library and CLI that scrapes free proxy listings from many public sources, verifies them and filters them by protocol, country, anonymity and speed. It ships a hosted daily-updated list, a proxypool style API surface and an MCP directory, and the underlying package is Apache 2.0 licensed.

**CharlesPikachu/freeproxy** — FreeProxy: Collecting free proxies from internet. (全球海量高质量免费代理，支持爬取数十个免费代理分享源，支持自定义规则代理筛选，爬虫与数据分析必备，每日更新海量免费代理。)

- Repository: https://github.com/CharlesPikachu/freeproxy
- Website: https://freeproxy.readthedocs.io/
- Stars: 566 · Forks: 99
- Language: Python
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/charlespikachu-freeproxy

## What the project actually does

freeproxy is described as a Python library that continuously discovers, verifies and updates free proxy lists for HTTP, HTTPS, SOCKS4 and SOCKS5, with filtering by geography, anonymity, speed and more.

The word that does the most work in that sentence is verifies. Collecting a list of proxy addresses is trivial, and the value of a library like this is entirely in the checking step. A public proxy list scraped from a website is a list of strings that may or may not be alive, may be transparent, may sit in a different country from the one advertised, and may die within minutes. The alternative to verifying is paying for a service that has already done that work.

The project is structured as a package named freeproxy on PyPI as pyfreeproxy, with a CLI, an MCP directory at the root of the repository, and an examples/ICU996 directory named after the 996icu source that appears in the topic list. There is a scripts/ directory, a docs/ directory built with readthedocs, a Makefile, a CITATION.cff, and a proxies.json at the repository root which is the checked-in list, updated by a GitHub Actions workflow whose badge in the README is labelled Update Proxies.json.

The README also points at a live list hosted at charlespikachu.github.io/freeproxy/, described as the latest free high quality proxies, which means you can consume the output without installing anything at all.

The licence is Apache 2.0, and the author is Zhenchao Jin.

## One class per proxy source

The supported sources table is the most informative part of the README. Each row names a source in English and Chinese, shows which protocols that source is known to serve, and links the module that implements it.

The naming convention is consistent: Advanced.Name becomes ADVFPProxiedSession, Databay becomes DatabayProxiedSession, FreeProxyDB becomes FreeProxyDBProxiedSession, FreeVPNNode becomes FreeVPNNodeProxiedSession. The Chinese column carries the same sites under their Chinese names, which makes sense for a set of sources that are largely Chinese-language sites.

The protocol columns are where the interesting information is, because they vary per source rather than being uniform. Advanced.Name, ChillyProxy and Dpangestuw are marked as supporting all four protocols, HTTP, HTTPS, SOCKS4 and SOCKS5. Databay supports HTTP, HTTPS and SOCKS5 but not SOCKS4. FreeProxyList supports HTTP, HTTPS and SOCKS4 but not SOCKS5. FreeProxyDB and FreeVPNNode support HTTP, SOCKS4 and SOCKS5 but are marked as not supporting HTTPS.

Those marks are claims about what each site publishes, not about what the library will find after verification. A source can list a proxy as SOCKS4 and the proxy can still be dead or lying about its protocol. What the table gives you is a starting expectation of which sources are worth querying for which protocol.

The changelog shows the source list being churned continuously. Version 0.5.0 in July 2026 added ChillyProxy, FreeProxyWorld and ProxySpace after fixing three invalid sources, 0.5.1 in August fixed ProxyShare and ProxyVerity and added ProxyLister and LitPort, and 0.5.2 in September removed TrustyTechProxiedSession and added HProxyProxiedSession. The monthly cadence of these maintenance releases, with each one naming fixed and added sources, is an honest signal about the nature of the project: sources rot, and the library's job is to track that.

## Installing it and the dependency set

The package is on PyPI as pyfreeproxy, and the Makefile shows the local installation path:

```makefile
.PHONY: install

install:
	python setup.py install

develop:
	python setup.py develop
```

The develop target is the one to use if you intend to work on the code, and the Makefile also has a publish target that builds an sdist and a wheel and uploads them with twine.

The dependency list is where the design becomes clear. It is read straight from requirements.txt at install time:

```
requests>=2.32.5,<3
beautifulsoup4>=4.14.3,<5
fake-useragent>=2.2.0,<3
prettytable>=3.17.0,<4
lxml>=6.0.2,<7
platformdirs>=4.9.4,<5
DrissionPage>=4.1.1.2,<5
json-repair>=0.58.6,<1
tqdm>=4.67.3,<5
quickjs>=1.19.4,<2
pycountry>=26,<27
brotli>=1.0.9,<2
typing_extensions>=4.16.0,<5
```

Four of these choices are worth explaining. fake-useragent is there because free proxy list pages and the targets behind them inspect the client, and rotating the user agent is part of not being trivially blocked. DrissionPage is a browser automation library, which is needed for the sources that render their lists with JavaScript rather than serving static HTML. json-repair handles malformed JSON from scraped pages, and quickjs is a JavaScript interpreter embedded in Python, which is a strong hint that at least one source delivers its data by executing script rather than by parsing markup.

pycountry gives the country names behind the country codes the filters use, prettytable formats the CLI output, and tqdm draws the progress bar while sources are being scraped.

The setup.py reads the package metadata from the freeproxy module itself, so the version, description, author and licence all live in one place in the code rather than being duplicated in the packaging script.

## Why the proxies need a browser and a JavaScript engine

The dependency list points at a mechanism that is worth understanding, because it explains why a proxy harvester is not a simple HTTP loop.

Scraping a free proxy list website is adversarial work in a way that scraping, say, a documentation page is not. The site is defending itself against exactly this, and the defences are layered. Cloudflare-style interstitial challenges require JavaScript to run before the real page appears. The content may be assembled by a script that fetches the list as JSON from an endpoint. The list may be embedded in the page as a JavaScript variable rather than as table rows. And the site's own request needs to look like a browser, which is where fake-useragent and DrissionPage come in.

quickjs is the interesting one. Embedding a JavaScript interpreter in a Python process means the harvester can execute the page's script locally, extract the value it computes, and parse the result, without launching a full browser for every source. That is a large speed and memory saving across dozens of sources, and it explains why the library can refresh a whole pool on a schedule.

The practical consequence is that freeproxy is heavier to install and run than a naive list-scraper would be. A browser automation stack, an embedded JS engine, a JSON repair pass and a rotating user agent are all moving parts that need a working network stack, and some of them will behave differently on a headless server than on a desktop. That is the cost of harvesting sources that actively resist being harvested, and it is the same reason those sources exist to be used by someone else.

There is also a security dimension nobody should skip. These scripts fetch and execute code from websites you do not control, and the JSON repair step is parsing untrusted output. Running this on a machine with credentials or important data on it deserves thought.

## The MCP directory and the hosted list

Two distribution options sit alongside the library, and they suit different users.

The hosted list at charlespikachu.github.io/freeproxy/ is the zero-install path. The GitHub Actions workflow that keeps proxies.json updated runs on a schedule, so the list is maintained by someone else's cron job rather than yours. For a script that needs a proxy for a one-off check, pulling the current list is enough and no local machinery is required at all.

The mcp/ directory at the repository root is the other option, and it is worth noting because it is a newer kind of integration point. Putting an MCP server in a scraping library means an AI assistant can query the proxy pool directly, ask what proxies are available for a given country and protocol, and use them, rather than the assistant writing Python against the API. For tooling that already speaks MCP, that removes a layer of glue.

Neither route changes the underlying economics of free proxies. The pool is shared, it is monitored by many parties, and individual entries have a short useful life. The verification step in the library exists precisely because that is true, and it means the cost of using this project is that you run verification work yourself unless you take the hosted list as-is.

The README's own framing is that this is for crawling and data analysis, and it says so in the repository description too. The topics list names crawler, spider, proxypool, requests, proxy-checker, iplocation, iplocator and 996icu, which is a coherent set for that audience.

## Where freeproxy is the wrong choice

Three limits are structural and worth being blunt about.

The first is that free proxies are hostile to the thing you usually want a proxy for. A public proxy sees your traffic, and the people running it are not your friends. For anything involving credentials, session cookies, personal data or an authenticated API, routing traffic through a free proxy is a data leak you chose. The library's own filtering by anonymity is a partial mitigation and not a substitute for using a proxy you pay for.

The second is reliability. Verification at collection time tells you the proxy worked once. A free proxy's job is to be up briefly, collect whatever it can, and move on, and many are honeypots or monitoring nodes. The 996icu and similar sources in particular are frequently reported as flooded with dead or hijacked entries. Any workload that depends on a proxy staying up for minutes will not be served well by a pool of free addresses, and the README's own claim of continuous updating is about refreshing the list, not about guaranteeing any individual entry's lifetime.

The third is the legal and ethical surface. Proxy lists are harvested from sites that publish them, and the terms of those sites, and the jurisdictions the traffic crosses, vary. Using a proxy to reach content you are not authorised to reach is a different activity from using one to test your own crawler's robustness, and this library does not distinguish between those uses.

The alternative approach is a paid proxy provider or a residential proxy network, where the difference is not the interface but the guarantees: a stable address, a stated protocol, a known country, and a provider who has a legal basis for the traffic. The trade is cost against control, and freeproxy sits at the extreme end of cheap, which is exactly why it is useful for testing a crawler's robustness and a bad choice for production traffic.

## Conclusion

freeproxy suits a scraping or data collection project that needs a pool of proxies for testing, geo-distribution experiments or reach checks, and where paying for a proxy list is not on the table, since the library handles source scraping, verification and filtering rather than just handing you a text file. It is the wrong tool for anything that needs a stable, fast or anonymous connection, because free proxies are shared, monitored and short-lived, and it is the wrong tool if your use of proxies is to evade access controls. Verify first which protocol and country combinations actually survive verification on your network, and note that the newest release is v0.5.2 from 2026-09-16 with the last push on 2026-10-20 and no GitHub releases.

## FAQ

### What does freeproxy do?

It continuously discovers, verifies and updates free proxy lists for HTTP, HTTPS, SOCKS4 and SOCKS5, with filtering by geography, anonymity, speed and more. The package is on PyPI as pyfreeproxy and the README points to a live list at charlespikachu.github.io/freeproxy/.

### How do I install freeproxy?

From PyPI as pyfreeproxy, or from a clone with make install, which runs python setup.py install. The Makefile also has a develop target that runs python setup.py develop, and a publish target that builds and uploads with twine.

### Why does freeproxy depend on DrissionPage and quickjs?

Free proxy list pages defend themselves against being scraped, so the harvester needs to render JavaScript and to look like a browser. DrissionPage provides browser automation, quickjs embeds a JavaScript interpreter so script-computed values can be extracted without launching a full browser, and fake-useragent rotates the client identity.

### How often do the proxy sources change?

The releases show monthly maintenance. Version 0.5.0 in July 2026 added ChillyProxy, FreeProxyWorld and ProxySpace after fixing three invalid sources, 0.5.1 in August 2026 added ProxyLister and LitPort, and 0.5.2 in September 2026 added HProxyProxiedSession and removed TrustyTechProxiedSession.

### Can I use the proxy list without installing anything?

Yes. The README points at a live list at https://charlespikachu.github.io/freeproxy/, and the repository root carries a proxies.json that a GitHub Actions workflow keeps updated.

### What licence is freeproxy released under?

Apache 2.0. The setup.py classifier lists License :: OSI Approved :: Apache Software License and the licence field is read from the package metadata, with a LICENSE file at the repository root.

## Sources

- [CharlesPikachu/freeproxy on GitHub](https://github.com/CharlesPikachu/freeproxy)
- [Issues](https://github.com/CharlesPikachu/freeproxy/issues)
- [License: Apache-2.0](https://github.com/CharlesPikachu/freeproxy/blob/master/LICENSE)
- [Project website](https://freeproxy.readthedocs.io/)
- [README](https://github.com/CharlesPikachu/freeproxy/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/charlespikachu-freeproxy