Principle:Langgenius Dify Plugin Installation

Knowledge Sources	Dify
Domains	Plugin_System, Marketplace, Frontend
Last Updated	2026-02-12 00:00 GMT

Overview

Description

Plugin Installation defines the mechanisms through which plugins are delivered into a running Dify workspace. The principle establishes a multi-source installation model where plugins can originate from three distinct channels: the Dify Marketplace, a GitHub repository, or a locally uploaded file (either a single .pkg package or a .bundle containing multiple plugins). Each channel has its own upload/install endpoint, but all channels converge on a common asynchronous task-based installation pipeline that returns a task ID for progress tracking.

The upgrade path is treated as a first-class concern. Marketplace upgrades swap the original_plugin_unique_identifier for a new_plugin_unique_identifier, while GitHub upgrades additionally carry repository, version, and package metadata. This ensures that upgrades preserve the installation lineage and allow rollback decisions.

Usage

Plugin Installation is invoked when a user:

• Clicks "Install" on a marketplace plugin, triggering updateFromMarketPlace or direct install hooks.
• Provides a GitHub repository URL with a specific version and package, triggering uploadGitHub to resolve the package and then the install endpoint.
• Drags or selects a local .pkg or .bundle file, triggering uploadFile which sends the file as multipart/form-data.

All three paths result in an InstallPackageResponse containing a task_id and an all_installed boolean indicating whether the installation completed synchronously or requires polling.

Theoretical Basis

The multi-source installation model reflects the Strategy pattern (Gang of Four), where the installation strategy varies by source but the post-installation behavior (task tracking, plugin list refresh) remains identical. Key design principles include:

• Asynchronous task model -- Plugin installation may involve downloading, extracting, validating, and registering a plugin. Rather than blocking the UI, the system returns a task ID immediately and the frontend polls for completion. This follows the Command Query Responsibility Segregation (CQRS) pattern where the command (install) and query (check status) are separate operations.
• Idempotent upgrades -- The upgrade endpoints accept both the old and new unique identifiers, making the operation idempotent: re-submitting the same upgrade request does not create duplicate installations.
• Content-type adaptation -- File uploads use multipart/form-data via XMLHttpRequest, while marketplace and GitHub installations use JSON POST bodies. The service layer abstracts this difference so consumers interact with a uniform async function signature.

Related Pages

• Implementation:Langgenius_Dify_UpdateFromMarketPlace