Dify DSL Explained: Export Apps as YAML for Delivery and Migration

With Dify DSL, you can hand an app you built to another workspace or move it to another environment. Knowing what goes into the file and what does not before delivery or migration reduces the setup work for the recipient.

The content of this article was checked against the official Dify documentation and the source code on GitHub on October 2, 2026. Screens and specifications may change. Before using it, check the latest content through the sources at the end.

What Dify DSL is

DSL stands for Domain Specific Language. The official Dify documentation explains that every Dify app can be exported to a YAML file in Dify's own DSL. You can also create an app directly from that DSL file. It is designed to make moving apps to another Dify instance and sharing them with others easier.

The file format is YAML, not JSON like n8n workflows. If you want to import a JSON file into Dify, first check whether the original file is a DSL exported from Dify. The official documentation positions DSL as the standard for keeping app settings together in YAML format.

A DSL contains the app settings and metadata, workflow and node settings, and model parameters and prompts. The content is text, so you can open and read it in an editor. Before handing it over, open it and check by eye that no API keys or internal information remain.

When to use DSL

• Delivery: hand an app you built to the client's workspace
• Migration: move an app built in a test environment to production
• Backup: keep the settings before making major changes to an app or deleting it

If you only want to duplicate an app within the same workspace, you do not need DSL. According to the official documentation, duplicating copies all settings, prompts and workflows, and the original app stays as it is. DSL is useful when you cross workspaces or Dify environments. Once you delete an app, its settings and logs cannot be restored, so the official documentation recommends making a DSL backup before deleting.

How to export a DSL

The official documentation lists two ways to export.

1. On the Studio page, choose “Export DSL” from the app's menu
2. In the app editor, choose “Export DSL” at the top left

If the app uses environment variables of the Secret type, you are asked whether to include them in the export. When exporting for delivery or sharing, choose not to include them. If you include them, values such as API keys go into the YAML file.

Save the exported file with the app name and export date in the file name. When you deliver a fixed version later, it is easier to confirm with the client which file is the latest.

Dify environment variables let you keep secrets such as API keys outside the app, so they are not visible when you share the DSL. If you put API keys in environment variables instead of writing them directly in prompts or node settings, you can hand over the exported file with confidence.

How to import a DSL

The official documentation describes the import flow as follows.

1. Upload the DSL file (YAML format)
2. Dify checks version compatibility
3. If the DSL version is older than the current Dify, a warning is shown
4. An app is created from the file's settings

After importing, set up the model providers and tool credentials again. If the app uses knowledge, create the knowledge and reconnect it to the app. Finally, check its behavior with test input before publishing.

How much work the recipient has depends on how thoroughly the sender wrote the instructions. If the setup order matches the steps in the instructions, the client only needs to work through them from the top. When something is unclear, it is also easier to say which step they got stuck on.

What the export leaves out: API keys and knowledge

The official documentation lists what is not exported: API keys for third-party tools, the actual content of knowledge, and usage logs and analytics data. For knowledge, only the connection settings are exported, not the document data.

The Dify source code (main branch on GitHub, checked October 2026) also does the following during export.

• Lists the plugins the app uses as dependencies
• Exports knowledge IDs in knowledge retrieval nodes in a form encrypted per workspace
• When Secrets are excluded, removes credential IDs from tool nodes
• Clears Webhook trigger URLs
• Resets schedule trigger settings to default values

As a result, the recipient may need to install plugins, set up credentials, check Webhook URLs and reconfigure schedules. Write these in the instructions.

Moving to an environment on a different version

For Dify Cloud, the official documentation explains that it always runs the latest DSL version, so imported files are compatible. The documentation for self-hosted Dify says that to import a DSL made in a newer Dify, you may first need to upgrade Dify.

The source code compares the version written in the DSL with the version of the importing side and handles each case differently.

If the client self-hosts Dify, ask for their Dify version before delivery. If your environment is newer, decide whether to rebuild in an environment on the same version as theirs or have them upgrade Dify. The same applies when moving an app built on Dify Cloud to the client's self-hosted Dify. If it was imported with a warning, open each node one by one and check that the settings are as intended.

Chatflow and Workflow apps also have version control. Published versions are recorded, and you can load an earlier version back into the draft. Naming the delivered version makes it easy to identify when you fix it later. The difference between the two types is covered in Dify Chatflow vs. Workflow.

Instructions to include with the deliverable

A DSL file alone may not be enough for the recipient to run the app. Write the following in the instructions.

• The app's purpose and the flow from input to output
• The environment it was built in (cloud or self-hosted) and the Dify version
• The model providers used, and how to issue API keys
• Required plugins and how to install them
• Environment variable names and a description of the values to enter (not the values themselves)
• Documents to put into knowledge, and steps to create it
• How to reconfigure Webhooks and schedules
• Example inputs for testing, and the expected results

If you self-host Dify and use it commercially, also check the license terms. They are covered in Dify commercial use.

On Employee Store, you hand over the DSL file and instructions through the delivery box for each transaction. Delivery is due within 3 business days in principle, and the buyer is refunded if it is late. The buyer checks the deliverable in the transaction room and confirms receipt. For what to write on the listing page, see How to write an AI agent description. For the transaction flow, see How to use Employee Store.