v2ray-finder

فارسی | English | Deutsch | 📋 CHANGELOG

A high-performance tool to fetch, aggregate, validate and health-check public V2Ray server configs from GitHub and curated subscription sources.

Built with love for eternal freedom ❤️

🗂️ Repository Structure

This is a monorepo containing two independent implementations of v2ray-finder:

Each implementation is self-contained. You can use either one independently.

🐍 Python — Quick Start

from v2ray_finder import Pipeline, StopController

pipeline = Pipeline(check_health=True)
result = pipeline.run()
for score in result.scores[:5]:
    print(score.grade, score.config[:80])

pip install v2ray-finder                # core
pip install "v2ray-finder[async]"       # + httpx for concurrent fetch
pip install "v2ray-finder[all]"         # everything

Full Python docs: README.en.md | فارسی: README.fa.md | Changelog: CHANGELOG.md

⚡ .NET — Quick Start

See dotnet/README.md for installation and usage.

🚀 What's New in v0.7.0 (Python)

🛡️ Structured error model — FetchResult.structured_error with category / kind / message hierarchy (V1-D2)
🔄 xray Layer-3 port-contention retry — auto-retry on a fresh OS port when xray fails to bind (V1-D4)
🖥️ GUI fully migrated to Pipeline — Stop button, real progress bar, Score/Grade/Latency columns, Failed Sources panel (V1-A2)

🧪 Test Coverage (Python)

~85% across Python 3.8–3.12, Linux, macOS & Windows.

📝 License

Apache License 2.0 © 2026 Ali Sadeghi Aghili

This project is licensed under the Apache License 2.0. Any derivative work, port, or redistribution must retain the NOTICE file and credit the original author. See LICENSE for full terms.