flutter_v2ray_client

Open Source Love pub package likes pub points

Tip

🚀 Available on All Platforms - Now Including iOS! (App Store Safe)

 

✨ Premium Features

🔒 2-Year Guarantee
Free updates & maintenance included

💎 Priority Support
Direct, fast help for all premium users

🚀 Advanced Features
Unlock exclusive premium capabilities

💡 Need help or have questions? We're here to help! Contact us for quick assistance or to discuss your needs.

Table of contents

âš¡ Features

  • Run V2Ray Proxy & VPN Mode
  • Get Server Delay (outbound and connected)
  • Parsing V2Ray sharing links and making changes to them
  • Built-in socket protection for Android VPN tunneling
  • Live status updates: connection state, speeds, traffic, duration

📸 Screenshots

iOS
iOS
Android
Android Main Screen   Android Logs Screen
Windows
Windows
macOS
macOS
Linux
Linux

Example app demonstrating flutter_v2ray_client features across all platforms


📱 Supported Platforms

Platform Status Info Type
Android Done ✅ Xray 25.10.15 Free
iOS Done ✅ Xray 25.10.15
HevSocks5Tunnel 5.14.1		 Buy Now
Windows Done ✅ Xray 25.10.15
Sing Box 1.12.10		 Buy Now
Linux Done ✅ Xray 25.10.15
Sing Box 1.12.10		 Buy Now
macOS Done ✅ Xray 25.10.15
Sing Box 1.12.10		 Buy Now
Browser Extension Coming Soon Chrome, Firefox, Edge Premium

🚀 Get started

🔗 Add dependency

You can use the command to add flutter_v2ray_client as a dependency with the latest stable version:

$ flutter pub add flutter_v2ray_client

Or you can manually add flutter_v2ray_client into the dependencies section in your pubspec.yaml:

dependencies:
  flutter_v2ray_client: ^3.0.0

💡 Examples

URL Parser

import 'package:flutter_v2ray_client/flutter_v2ray.dart';

// v2ray share link like vmess://, vless://, ...
String link = "link_here";
V2RayURL parser = V2ray.parseFromURL(link);

// Remark of the v2ray
print(parser.remark);

// generate full v2ray configuration (json)
print(parser.getFullConfiguration());

Edit Configuration

// Change v2ray listening port
parser.inbound['port'] = 10890;
// Change v2ray listening host
parser.inbound['listen'] = '0.0.0.0';
// Change v2ray log level
parser.log['loglevel'] = 'info';
// Change v2ray dns
parser.dns = {
    "servers": ["1.1.1.1"]
};
// and ...

// generate configuration with new settings
parser.getFullConfiguration()

Making V2Ray connection

import 'package:flutter_v2ray_client/flutter_v2ray.dart';

final V2ray v2ray = V2ray(
    onStatusChanged: (status) {
        // Handle status changes: connected, disconnected, etc.
        print('V2Ray status: ${status.state}');
    },
);

// You must initialize V2Ray before using it.
await v2ray.initialize(
    notificationIconResourceType: "mipmap",
    notificationIconResourceName: "ic_launcher",
);

// v2ray share link like vmess://, vless://, ...
String link = "link_here";
V2RayURL parser = V2ray.parseFromURL(link);

// Get Server Delay
print('${await v2ray.getServerDelay(config: parser.getFullConfiguration())}ms');

// Permission is not required if using proxy only
if (await v2ray.requestPermission()){
    v2ray.startV2Ray(
        remark: parser.remark,
        // The use of parser.getFullConfiguration() is not mandatory,
        // and you can enter the desired V2Ray configuration in JSON format
        config: parser.getFullConfiguration(),
        blockedApps: null,
        bypassSubnets: null,
        proxyOnly: false,
    );
}

// Disconnect
v2ray.stopV2Ray();

Exclude specific apps from VPN (blockedApps)

// Provide Android package names to exclude from VPN tunneling.
// Traffic from these apps will NOT go through the VPN tunnel.
final List<String> blockedApps = <String>[
  'com.whatsapp',
  'com.google.android.youtube',
  'com.instagram.android',
];

await v2ray.startV2Ray(
  remark: parser.remark,
  config: parser.getFullConfiguration(),
  blockedApps: blockedApps, // <— excluded from VPN
  bypassSubnets: null,
  proxyOnly: false,
);

Tips:

  • Android package names are required (e.g., com.example.app).
  • To find a package name, you can:
    • Use: adb shell pm list packages | grep <keyword>
    • Or check Play Store URL (e.g., id=com.whatsapp).
  • If you want to make this user-selectable, let users pick apps then store their package names and pass them as blockedApps.
  • This mirrors how the app code uses blockedApps in lib/services/v2ray_service.dart when starting V2Ray.

Bypass LAN Traffic

final List<String> subnets = [
    "0.0.0.0/5",
    "8.0.0.0/7",
    "11.0.0.0/8",
    "12.0.0.0/6",
    "16.0.0.0/4",
    "32.0.0.0/3",
    "64.0.0.0/2",
    "128.0.0.0/3",
    "160.0.0.0/5",
    "168.0.0.0/6",
    "172.0.0.0/12",
    "172.32.0.0/11",
    "172.64.0.0/10",
    "172.128.0.0/9",
    "173.0.0.0/8",
    "174.0.0.0/7",
    "176.0.0.0/4",
    "192.0.0.0/9",
    "192.128.0.0/11",
    "192.160.0.0/13",
    "192.169.0.0/16",
    "192.170.0.0/15",
    "192.172.0.0/14",
    "192.176.0.0/12",
    "192.192.0.0/10",
    "193.0.0.0/8",
    "194.0.0.0/7",
    "196.0.0.0/6",
    "200.0.0.0/5",
    "208.0.0.0/4",
    "240.0.0.0/4",
];

v2ray.startV2Ray(
    remark: parser.remark,
    config: parser.getFullConfiguration(),
    blockedApps: null,
    bypassSubnets: subnets,
    proxyOnly: false,
);

View and manage V2Ray logs (Android)

import 'package:flutter_v2ray_client/flutter_v2ray.dart';

final v2ray = V2ray(onStatusChanged: (_) {});

// Fetch logs from Android logcat (oldest -> newest)
final List<String> logs = await v2ray.getLogs();

// Clear logcat buffer (Android only)
final bool cleared = await v2ray.clearLogs();

Notes:

  • Android only. Other platforms return empty results / true on clear.
  • Logs are returned in chronological order (oldest → newest).
  • Internally, the plugin keeps a small in-memory buffer capped at ~500 lines for low memory usage.
  • The example app includes a "View Logs" page with:
    • Search/filter text box
    • Copy button that copies currently filtered logs and prefixes type: ERROR, WARN, INFO
    • Refresh to re-fetch from logcat
    • Clear to clear logcat
    • Automatic scroll to bottom on refresh and search
    • Bottom-only safe area padding so content stays above navigation gestures

🤖 Android configuration before publish to Google Play🚀

Android 16 KB Page Size Support

This package fully supports Android's 16 KB page size, ensuring compatibility with the latest Android devices and requirements for Google Play Store publishing. The plugin is built with modern Android development practices that handle both 4 KB and 16 KB page sizes seamlessly.

gradle.properties

  • add this line
android.bundle.enableUncompressedNativeLibs = false

build.gradle (app)

  • Find the buildTypes block:
buildTypes {
        release {
            // TODO: Add your own signing config for the release build.
            // Signing with the debug keys for now, so `flutter run --release` works.
               signingConfig signingConfigs.release
        }
    }
  • And replace it with the following configuration info:
splits {
        abi {
            enable true
            reset()
            //noinspection ChromeOsAbiSupport
            include "x86_64", "armeabi-v7a", "arm64-v8a"

            universalApk true
        }
    }

   buildTypes {
        release {
            // TODO: Add your own signing config for the release build.
            // Signing with the debug keys for now, so `flutter run --release` works.
               signingConfig signingConfigs.release
               ndk {
                //noinspection ChromeOsAbiSupport
                abiFilters "x86_64", "armeabi-v7a", "arm64-v8a"
                debugSymbolLevel 'FULL'
            }
        }
    }

🔮 Roadmap & Future Enhancements

🚀 Performance Improvements

  • hev-socks5-tunnel Integration: Implement hev-socks5-tunnel for significantly better performance in terms of speed and resource usage
  • High-performance SOCKS5 tunneling with lower CPU and memory consumption
  • Enhanced connection stability and throughput

🌟 Planned Features

  • Enhanced multi-platform support (iOS, Windows, Linux, macOS)
  • Advanced traffic routing and filtering options
  • Improved user interface components
  • Extended protocol support
  • Widgets for mobile devices

💡 Community Contributions

We welcome contributions from the community! If you're interested in helping implement any of these features, please check our contribution guidelines and feel free to open issues or pull requests.

📋 Attribution

This project uses third-party libraries and resources. See 📋 ATTRIBUTION.md for details.

All rights reserved.

💰 Donation

If you liked this package and want to accelerate the development of iOS and desktop platform support, consider supporting the project with a donation below. Your contributions will directly help bring flutter_v2ray_client to more platforms faster!

Cryptocurrency & Bitcoin donation button by NOWPayments

Libraries

flutter_v2ray
flutter_v2ray_method_channel
flutter_v2ray_platform_interface
model/v2ray_status
url/shadowsocks
url/socks
url/trojan
url/url
url/vless
url/vmess