Getting Started with Dify Plugin Development

Who this is for

This guide is for developers who want to write their own Dify plugin, whether a tool, a model provider or an extension. By the end you will have installed the dify command, generated a Python plugin project, configured remote debugging, and run the plugin.

What a plugin is

Dify plugins are modular components that extend the AI apps you build with Dify through external services, custom functionality and specialized tools. Through plugins, an AI app can connect to external APIs, process different types of data, perform specialized calculations and carry out real-world actions^[1].

There are six plugin types: model, tool, agent strategy, extension, datasource and trigger^[1]. Two of them have rules worth knowing. A tool plugin can also implement endpoints; a Discord bot, for example, needs to both send and receive messages. A model plugin is strictly for model providers, and no other extensions are allowed in it^[2].

Before you start

You need Python 3.12^[2]. Homebrew is needed only on macOS, where it installs the CLI^[2].

The dify command in this guide is the plugin development CLI. It is a different tool from difyctl, which manages Dify apps from the command line^[2].

Step 1: install the CLI

On macOS, install with Homebrew:

brew tap langgenius/dify
brew install dify

On Linux, download the latest binary from the Dify Plugin Daemon releases page on GitHub. Choose dify-plugin-linux-amd64 for x86_64 hosts or dify-plugin-linux-arm64 for ARM hosts^[2]. Then make the file executable and move it to /usr/local/bin/dify^[2]:

chmod +x dify-plugin-linux-amd64
sudo mv dify-plugin-linux-amd64 /usr/local/bin/dify

On Windows, download dify-plugin-windows-amd64.exe, or the arm64 build on ARM devices. Rename it to dify.exe and add its folder to PATH^[2]. If you skip the PATH step, your terminal will not find the dify command.

Check the installation with this command:

dify version

Step 2: create a plugin project

Create a new project with this command^[2]:

dify plugin init

The wizard asks for the plugin name, author, description and an optional repository URL. It can also generate a multilingual README, and English is required by default^[2]. Next, choose python for the Python template, then choose the plugin type. The templates include tool, agent-strategy, llm, text-embedding, rerank, tts, speech2text, moderation, extension, datasource and trigger^[2]. When the wizard asks for a minimal Dify version, leave it blank to use the latest version^[2].

The CLI creates a directory named after the plugin, with the basic project structure inside. The example plugin is called hello-world, so enter it with:

cd hello-world

If you are not sure which plugin type to choose, the Dify docs include a short decision guide that compares the tool, model, agent strategy, extension, datasource and trigger types^[1]. The CLI covers the development workflow only. Packaging a plugin and sharing it on the Marketplace is documented separately^[1].

Step 3: configure remote debugging

Copy the environment template first^[2]:

cp .env.example .env

To get the debug credentials, log in to your Dify environment, click Plugins (插件) at the top right, and then click the debug icon. In the pop-up window, copy the API Key and the Host Address^[2]. Put them into .env, following this example:

INSTALL_METHOD=remote
REMOTE_INSTALL_URL=debug-plugin.dify.dev:5003
REMOTE_INSTALL_KEY=********-****-****-****-************

REMOTE_INSTALL_URL combines the host and the port in host:port form. The two values appear together on the API Key card of the plugin page^[2].

Step 4: install dependencies and run

From the project directory, run^[2]:

pip install -r requirements.txt
python -m main

The debug credentials come from the plugin page of your Dify environment. If you switch to a different environment, copy the credentials again from that one^[2].

Where to go next

The plugin type selection guide, and the notes on development, debugging and publishing, are in the plugin development section of Dify's documentation^[1].

Adapted from Dify's documentation pages "Getting Started with Dify Plugin Development" and "Dify Plugin CLI"^[1][2], released under the CC BY 4.0 license.