Offline Deployment Guide for Dify

If your computer (or server) cannot connect to the internet, you will find that Dify fails to run properly. The reason lies in the Plugin Marketplace and the installation function, which rely on public Python pip repositories. When the progress bar spins during plugin installation, the plugin is actually downloading dependencies from the internet. In an offline environment, this leads to infinite errors because the connection fails.

Common Solutions & Pain Points

A common solution in the community is Repackaging. This involves packing all necessary dependencies into the plugin itself, ensuring pip install is not needed in an offline environment.

This works fine when there are few plugins. However, as the number of plugins increases, there is a risk of missing dependencies or failing to package them correctly.

[!WARNING] Missing dependencies in an offline environment is fatal.

You might find that the plugin installs successfully offline, but upon restarting the system, plugin_daemon will attempt to fetch missing packages via pip. Without internet access, this fails, preventing the entire plugin_daemon from starting... and the system crashes.

Recommended Solution: Private Pip Mirror (Nexus3)

I recommend building a private pip mirror within your intranet.

Core Concept:

1. Set up the mirror completely in an environment with internet access.
2. Migrate the Nexus3 Docker container and its data to the offline environment.

Required Software: Nexus3 (Docker version).

Nexus3 (by Sonatype) is a powerful repository management system. It supports various software repositories (Maven, npm, Docker, PyPI, etc.) and is especially suitable for building private pip mirrors.

Key Advantage of Nexus3: It allows you to batch cache all the pip packages required by Dify (or other software) on your machine. Later, you simply import the Nexus3 container and data volume into the offline environment, and plugin installation/restarts will work flawlessly.

Nexus Pip Repository Concepts

1. Hosted Repository: Stores internally developed Python packages (supports uploads).
2. Proxy Repository: Proxies public PyPI sources (like Aliyun, Tsinghua, or official PyPI), caching commonly used packages.
3. Group Repository: Merges multiple repositories into a single URL.

Step 1: Preparation & Caching (Online Environment)

First, install Docker. Ensure you run the container and Dify on the same CPU architecture as your server (e.g., if the server is x86, perform these steps on an x86 online machine).

1. Start Nexus3 Container

mkdir /some/dir/nexus-data && chown -R 200 /some/dir/nexus-data
docker run -d -p 8081:8081 --name nexus -v /some/dir/nexus-data:/nexus-data sonatype/nexus3

[!IMPORTANT] /some/dir/nexus-data is your local path. It is crucial because it will store the pip cache. Ensure it is accessible and persistent.

2. Configure Nexus3

Access port 8081 in your browser: http://localhost:8081

Find the password file in the host volume to log in (default user: admin):

After logging in, it is recommended to enable anonymous access for easier debugging:

3. Create Pip Proxy Repository

Go to the Administration menu and create a repository:

We only need to create a proxy pip repository.

• If you need to upload local .whl packages, you would also create a hosted repository and merge them using a Group.

Set the Proxy destination (Remote storage). I recommend using the official PyPI source or a reliable mirror like Tsinghua:

4. Verify the Proxy

Uninstall a package (e.g., pandas) in your terminal, then try installing it using your newly created proxy:

pip uninstall pandas
pip install pandas -i http://127.0.0.1:8081/repository/dify/simple

(Note: Don't forget to add /simple to the URL)

If it installs, go back to Nexus3. You should see that pandas has been cached locally:

Success! The proxy is working.

5. Configure Dify to Use Private Source

Return to Dify's docker-compose file and search for pip:

Replace all instances of PIP_MIRROR_URL with your private source address:

PIP_MIRROR_URL: ${PIP_MIRROR_URL:-http://host.docker.internal:8081/repository/dify/simple}

[!TIP] host.docker.internal resolves to the host IP (127.0.0.1) inside Docker containers. If your Nexus3 is on a different machine, replace this with the target IP.

6. Batch Cache Plugin Dependencies

Start Dify. Install ALL the plugins you intend to use offline while still in the online environment.

Check Nexus3 again. You will see thousands of new packages:

This means the plugin dependencies are now cached. It is recommended to restart Dify once online to ensure everything is stable.

Step 2: Migration to Offline Environment

Success! Now, transfer the Dify docker images, the Nexus3 docker image, and the cache data folder to your offline environment.

1. Start Nexus3 on Offline Server

docker run -d -p 8081:8081 --name nexus -v /some/dir/nexus-data:/nexus-data sonatype/nexus3

Ensure /some/dir/nexus-data points to the folder containing the pip cache data you copied from the online environment.

2. Verify Cache

Access the server IP at port 8081:

You will see all your cached packages are present!

3. Configure Offline Dify

In Dify's docker-compose.yaml:

Change PIP_MIRROR_URL to your offline server's IP address.

4. Start Dify & Install Plugins

Start Dify. You can now install plugins from the marketplace normally!

No repackaging needed, and no more dependency headaches!