# Using Plugins
- This page explains about the usage of Qv2ray plugin system
- To use a plugin, you need at least
Qv2ray v2.5.0-pre1 BuildVersion: 5264
# What is a plugin
Technically said, a Qv2ray Plugin is a shared library that implements
QvPlugininterface, which in order to extent the functionality of Qv2ray.
Qv2ray Plugin extends Qv2ray's functionality, which allows you use more features. By leveraging plugins, Qv2ray can even run without using V2Ray core at all.
Qv2ray workgroup has published 6 officially maintained plugins:
- QvPlugin-SS (opens new window) - Allows you to enable complete support of Shadowsocks SIP003 in Qv2ray
- QvPlugin-SSR (opens new window) - Allows you to use ShadowSocksR in Qv2ray
- QvPlugin-Trojan (opens new window) - Allows you to use NaiveProxy in Qv2ray
- QvPlugin-NaiveProxy (opens new window) - Allows you to use Trojan in Qv2ray
- QvPlugin-Command (opens new window) - Run any command when a specific event has been triggered
- QvPlugin-Trojan-Go (opens new window) - Allows you to use Trojan-Go in Qv2ray
Builtin Shadowsocks Support vs QvPlugin-SS
It is a common gotcha that people think Qv2ray needs QvPlugin-SS to support Shadowsocks. Qv2ray already has built-in Shadowsocks support (opens new window) from V2Ray Core, which will suffice general use cases. Therefore, you don't necessarily need to use QvPlugin-SS.
Though strongly unrecommended, however, if you insist on using outdated/deprecated ciphers (for example,
rc4-md5), you may need QvPlugin-SS to make them work. Servers with SIP003 plugins (for example,
simple-obfs (opens new window),
kcptun (opens new window) and
v2ray-plugin (opens new window)) will also require QvPlugin-SS to work.
# How to download and use a plugin
You can download and enable as many plugins as you want.
To install a plugin, you need to do these:
# 1. Download / Install the plugin
- Some plugins may be shipped via package manager (such as Scoop), you can use them if you want.
- Please go to step 3 if you have installed the plugin using this method.
- From a plugin’s release page, download the file according to your OS.
# 2. Put your plugin inside
- Click Open Local Plugin Folder in the Plugin Manager window, which a folder named
pluginswill be opened.
- Place your downloaded plugin
sofile into this directory.
# 3. Restart Qv2ray & Enable Plugins
- Open the “Plugin Manager”, you’ll see the plugin being found.
- Check the “enabled” checkbox on the left hand side.
- Some plugins, especially kernel plugins, will only be loaded after Qv2ray restarts.
# 4. Benefit!
- Your plugin is ready to use!
# Plugin FAQ
# Qv2ray doesn't recogonize the plugin:
- Please confirm the plugin in placed into Qv2ray's plugin directory (
- Please confirm the plugin version matches Qv2ray version. Currently, only Qv2ray
v2.6.0-rc2and later supports plugin version
- If the problem persists, you are welcome to report this issue directly to the plugin provider, please include:
- The exact information of Qv2ray, with the source of the program, Qv2ray version, and the build version.
- The exact version of the Plugin, with the sha256 or md5 of the plugin file.
- Qv2ray log, can be collected by executing
qv2ray(.exe) --debug > log.txt
# I cannot find a plugin file for my OS:
- This can happen if the plugin writer is lazy to support your OS, or
- The plugin is not suitable for your OS:
- e.g. A Linux-specific
iptablessetting plugin is not suitable on macOS and Windows
- e.g. A Linux-specific
# Qv2ray crashed after loading a plugin:
- Please try
qv2ray(.exe) --noPluginto skip loading all plugins.
- If the Qv2ray started successfully, please report the error using methods mentioned above.