How to Perform Platform-Agnostic Plugin Repackaging with the -p Option

The -p option in plugin_repackaging.sh enables you to download pre-built binary wheels for a specific target platform (such as manylinux2014_aarch64) while running the script on a different host architecture, producing an offline .difypkg file that installs cleanly on the target system.

Platform-agnostic plugin repackaging is essential when you need to deploy Dify plugins to environments with different CPU architectures or operating systems than your build machine. The junjiem/dify-plugin-repackaging repository provides a Bash automation script that handles cross-platform wheel compilation and offline packaging through a simple command-line interface.

Understanding the -p Flag and Platform-Agnostic Workflows

The -p flag bridges the gap between your build host and target deployment environment. When you invoke plugin_repackaging.sh with -p <platform-tag>, the script populates the PIP_PLATFORM variable (lines 68-73 in plugin_repackaging.sh) and passes it to pip download with the --platform and --only-binary=:all: flags.

This mechanism allows you to run the script on an x86_64 Linux machine but generate a package containing aarch64 (ARM64) binary wheels, or target specific manylinux versions for maximum compatibility.

How the -p Option Works Under the Hood

The platform-agnostic repackaging process follows a precise sequence defined in plugin_repackaging.sh:

1. OS and Architecture Detection

The script first detects the host OS (linux or darwin) and CPU architecture (amd64 vs arm64) to select the correct dify-plugin-<os>-<arch> binary (lines 20-24).

2. Platform Flag Parsing

When you provide -p manylinux2014_aarch64, the script constructs the PIP_PLATFORM variable containing --platform manylinux2014_aarch64 --only-binary=:all: (lines 13-14).

3. Cross-Platform Wheel Download

The script executes pip download with the platform flag against the configured mirror (https://mirrors.aliyun.com/pypi/simple), downloading pre-built binary wheels for the target architecture regardless of the host's capabilities.

4. Requirements Injection

The script prepends --no-index --find-links=./wheels/ to requirements.txt (lines 18-25), ensuring the dify-plugin binary resolves dependencies from the locally downloaded wheels instead of attempting to reach PyPI.

5. Re-packaging

Finally, the script invokes the platform-specific dify-plugin-<os>-<arch> binary to produce a new offline package (lines 39-44), resulting in a <name>-offline.difypkg file ready for deployment.

Practical Examples

Targeting ARM64 from an x86_64 Host

Run the following to repackage a Marketplace plugin for ARM64 (aarch64) while executing on an x86_64 machine:

./plugin_repackaging.sh -p manylinux2014_aarch64 market langgenius agent 0.0.9

This generates langgenius-agent-0.0.9-offline.difypkg, which installs cleanly on ARM-based Dify nodes.

Using Docker for CI/CD Pipelines

Containerize the repackaging process to ensure consistent builds across different CI environments:

FROM alpine:latest

COPY plugin_repackaging.sh /app/
COPY dify-plugin-linux-amd64 /app/

WORKDIR /app
CMD ["./plugin_repackaging.sh", "-p", "manylinux2014_x86_64", "market", "antv", "visualization", "0.1.7"]

Build and execute:

docker build -t dify-plugin-repackaging .
docker run --rm -v $(pwd)/output:/app dify-plugin-repackaging

Customizing Output Suffixes

Use the -s flag alongside -p to override the default offline suffix:

./plugin_repackaging.sh -p manylinux2014_x86_64 -s linux-arm64 market myauthor myplugin 1.2.3

This produces myauthor-myplugin-1.2.3-linux-arm64.difypkg instead of the default naming convention.

Repackaging Local .difypkg Files

Apply platform-agnostic repackaging to existing local packages:

./plugin_repackaging.sh -p manylinux2014_x86_64 local ./myplugin-1.0.0.difypkg

Key Implementation Details

The platform-agnostic functionality relies on specific components within the repository:

• plugin_repackaging.sh (lines 68-73): Parses -p and -s flags to populate PIP_PLATFORM and suffix variables.
• plugin_repackaging.sh (lines 20-24): Detects host OS and architecture to select the correct dify-plugin-<os>-<arch> binary.
• plugin_repackaging.sh (lines 13-14): Constructs the pip download command with --platform and --only-binary=:all: flags.
• Platform binaries: dify-plugin-linux-amd64, dify-plugin-linux-arm64, dify-plugin-darwin-amd64, and dify-plugin-darwin-arm64 perform the final packaging step (lines 39-44).

Summary

• The -p option enables platform-agnostic plugin repackaging by passing --platform and --only-binary=:all: to pip download.
• You can build packages for ARM64 on x86_64 hosts (or vice versa) by specifying the appropriate manylinux tag.
• The script automatically detects your host OS and architecture to select the correct dify-plugin-<os>-<arch> binary.
• Downloaded wheels are injected into requirements.txt with --no-index --find-links to ensure offline installation.
• Both Marketplace plugins (market command) and local packages (local command) support the -p flag.

Frequently Asked Questions

What platforms does the -p option support?

The -p option accepts any platform tag recognized by pip, including manylinux2014_x86_64, manylinux2014_aarch64, manylinux_2_28_x86_64, and win_amd64. The script passes this directly to pip download --platform, allowing you to target Linux ARM64, older glibc versions, or other Python wheel compatibility tags regardless of your host system.

Can I run the script on macOS to build for Linux?

Yes. The script detects your host OS (darwin) and architecture (amd64 or arm64) to select the appropriate dify-plugin-darwin-<arch> binary (lines 20-24). When you specify -p manylinux2014_x86_64, the script downloads Linux-compatible wheels using pip download --platform, then repackages them using the macOS binary, producing a Linux-compatible .difypkg file.

How does the script handle binary wheel downloads?

When you provide the -p flag, the script constructs a PIP_PLATFORM variable containing --platform <tag> --only-binary=:all: (lines 13-14, 68-73). This forces pip download to fetch only pre-compiled binary wheels for the specified platform tag from the configured mirror (https://mirrors.aliyun.com/pypi/simple), skipping source distributions that would require compilation on the target host.

Where are the platform-specific binaries located?

The platform-specific binaries (dify-plugin-linux-amd64, dify-plugin-linux-arm64, dify-plugin-darwin-amd64, dify-plugin-darwin-arm64) are located in the root directory of the repository. The script automatically selects the correct binary based on host OS and architecture detection (lines 20-24) and uses it to perform the final packaging step (lines 39-44).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}