How Dify app export and import with DSL files works
A team has built a Dify app in one workspace or instance and now needs the same app in another, such as staging to production or a new region. DSL export and import moves app configuration, workflow nodes, model parameters, prompts and knowledge base connections as YAML, but not third-party API keys, knowledge base content or usage logs. That split decides most of the work. The YAML file gives the destination the app's structure, while credentials, documents and history must be supplied or rebuilt in the target environment. Teams usually need this when they promote a tested workflow from a staging instance, copy a proven app into a second workspace, or rebuild an app after a platform change. According to the Dify app management docs, the export and import steps sit in the app management screens, so an operator with the right workspace role can run them without shell access.
Treat the DSL file as a copy of the app's design, not a backup of the deployment. It does not replace database backups, storage backups or the upgrade process described in the operations section, and it cannot restore a knowledge base or conversation history. Before importing, confirm with the owner of the target workspace which model providers are configured there, because the file references models by provider and name and the destination must already hold working credentials for them. Also check which knowledge bases the app connects to, since the connections point to resources that may not exist in the new environment. Plan a short checklist for each import: model credentials, knowledge bases, tool and MCP server configuration, and the variables the app expects at runtime.
Which export and import path fits which move
This table compares four routes for moving a Dify app: a single export and import, promotion between workspaces on one instance, a move between self-hosted instances, and a rebuild from a DSL file in a fresh environment. Read each row for what the DSL file carries, what your team must recreate by hand, and the setup it suits. The main takeaway is that the DSL file moves the app design, while credentials, knowledge base content and logs must be handled separately on every path.
| Path | What the DSL file carries | What the operator recreates | When it fits |
|---|---|---|---|
| Single export and import in one workspace | App configuration, workflow nodes, model parameters, prompts and knowledge base connections | Third-party API keys, MCP server entries and knowledge base content if the source content is absent | Duplicating an app to test a variant before changing the live version |
| Promotion between workspaces on one instance | The same app definition as a single export | Model credentials, MCP servers with matching identifiers, and knowledge base content in the target workspace | Moving an app from a staging workspace to a production workspace; the Community edition is limited to a single workspace |
| Move between self-hosted instances | The same app definition, without usage logs or knowledge base content | Credentials, MCP servers, knowledge bases and their content, plus a review of environment settings on the target | Moving a tested app from a test deployment to a production deployment or to new hosts |
| Rebuild from DSL in a new environment | The app definition only, as a baseline | Accounts, credentials, tools, MCP servers, knowledge bases and all content, built from scratch | Recovering an app after a failed install or when the source instance cannot be reached |
| Keeping DSL files in version control | A dated snapshot of each exported app definition | A consistent export step after each release and a naming convention for each file | Reviewing changes over time and restoring an earlier design during an audit or rollback |
Recreating MCP server identifiers in the target workspace
An exported Dify app points to MCP servers by identifier, not by a copy of the server itself. The target workspace must hold servers with matching identifiers before the imported app can call its tools, so these checks run in order: inventory, naming, recreation and verification.
Inventory MCP references in the DSL
Open the exported YAML and search for every tool node and tool reference that points to an MCP server. Record each identifier, the tool name it exposes and the workflow or agent node that calls it. Treat this list as the contract for the target workspace. Missing a reference is the most common cause of a tool failing after import, because the app imports cleanly and only breaks at runtime.
Agree identifier naming across environments
Set one naming convention for MCP server identifiers in development, staging and production, and write it down with the owner of each server. Identical names across environments let the same DSL run unchanged. If a team renames a server in one workspace, every app that references it breaks on import. Store the naming table next to the DSL files so reviewers can check it during promotion.
Recreate servers with matching identifiers
In the target workspace, add each MCP server from your inventory using the exact identifier the DSL expects. Point it at the target environment's endpoint and credentials, not the source environment's. Connection details, keys and auth headers are not carried in the export, so each server needs its own configuration here. Confirm that the server is enabled before importing the app, so the first run does not fail on a missing dependency.
Verify each tool call after import
Run every workflow path and agent turn that reaches an MCP tool, then check the tool input, the returned output and the logged error if one occurs. Use test inputs that do not write to production systems. Confirm that the tool list the server returns matches what the app expects, since a server that renamed or removed a tool will fail silently in some paths. Repeat this check after any change to the server or the DSL.
Control MCP changes through the DSL review
Require a review of the DSL diff whenever an MCP identifier, tool name or server endpoint changes. Store the DSL in version control with the naming table and inventory, so a reviewer can see which servers an app depends on. This turns an identifier change into a deliberate, reviewed event rather than a surprise discovered during a promotion.
How to export, import and verify a Dify app
This sequence moves a Dify app from one workspace or instance to another as a DSL file, with credentials, MCP servers and knowledge bases recreated on the target side. It ends with test conversations that confirm the app behaves the same way it did at the source.
Inventory every dependency before exporting
The app owner and the platform engineer list what the app relies on: model providers and their credentials, MCP servers the app calls, knowledge bases it retrieves from, plugins and tools in each node, and any service API keys that front the app. Record each MCP server by the identifier the app uses, because the export refers to servers by that identifier. The inventory is done when every node in the workflow maps to a named dependency that exists or will exist in the target. Confirm the exact identifiers in your own environment, since behavior can vary by Dify version.
Export the app as a DSL file
From the source workspace, the app owner exports the app as a YAML DSL file using the app management controls. The export carries app configuration, workflow nodes, model parameters, prompts and knowledge base connections. It does not carry third-party API keys, knowledge base content or usage logs, so those must be handled separately. The step is complete when the file is saved with a name that identifies the app and the source version, and the file opens as readable YAML.
Review the DSL file for secrets and environment references
Before the file leaves the source environment, a security engineer or the app owner reads it for anything that should not travel: inline credentials, internal hostnames, tokens in tool configuration, and URLs that point to source-only systems. Anything found is replaced with a placeholder or removed, and the change is noted. The review is complete when a search for common secret patterns and the source environment's hostnames returns nothing, and the reviewer has signed off in the change record. Store the reviewed file in version control, not in a shared drive.
Recreate credentials and MCP servers in the target
The platform engineer configures the target workspace before importing. Model providers are added with credentials issued for that environment, and each MCP server is recreated using the same identifier the exported app references. Plugins and tools the app depends on are installed at compatible versions. Check that the model provider list shows each provider as configured and that each MCP server is listed under the identifier the DSL file uses. Do not reuse source-environment keys in the target.
Import the DSL file into the target workspace
An app builder with import rights imports the reviewed DSL file into the target workspace or instance. The app appears as a new app with its workflow nodes, prompts and parameters. Some nodes may show warnings or missing references where a dependency was not recreated, and each warning must be resolved before testing. The step is complete when the workflow opens in the editor with no unresolved node errors and the app's configuration matches the source file.
Re-link knowledge bases to target datasets
Knowledge base content does not travel in the export, so the target needs its own knowledge bases. The knowledge owner creates or loads the datasets in the target, then the app builder points each retrieval node at the correct dataset. Confirm that retrieval settings such as the index method and retrieval strategy match what the source app expected. The step is done when each retrieval node resolves to a populated dataset and a test query returns passages from it.
Run test conversations and compare with the source
The app owner runs a fixed set of test prompts covering the main paths through the workflow, including branches, tool calls and knowledge retrieval. Each prompt is run in the source app and the target app, and the outputs are compared for structure and expected behavior. Confirm that model providers respond, that tool calls return results from the recreated MCP servers, and that retrieval returns relevant passages. The step closes when every test path passes, the results are recorded, and the app is cleared for publishing in the target.
Keeping DSL files under version control
DSL files suit Git because they are plain YAML text, so every change to a prompt, model parameter or workflow node appears as a line-level diff that a reviewer can read before it merges. Keep one directory per app, named for the app and its owning team, and export each app into its own file so that a change in one workflow never mixes with another in the same commit. Before you export, settle which version you are capturing. In Dify, drafts and the live (published) version can differ, and an export reflects the state you select, so confirm with your team that the file you commit is the version you intend to release. Use commit messages that state the app, the version and the reason for the change, such as a prompt revision or a model swap, so that the history can answer audit questions later.
Route prompt and model changes through the same pull request review you apply to application code. A useful review checklist covers the prompt text itself, the model provider and parameters, knowledge base connections, tool references and any new workflow branches. Tie each DSL commit to a release by tagging the repository with the Dify app version or your change ticket, and record which Dify platform version the app was built on, because the platform itself changes on its own schedule. Check the Dify releases page when you plan a platform upgrade so that you know whether the DSL format or tool behavior will change.
Set a hard rule that no secrets or customer data enter the repository. Exports do not carry third-party API keys, knowledge base content or usage logs, but prompts and test inputs can still contain personal or confidential information, so scan each commit for credentials and sample data before it is pushed. Store credentials in your secrets manager and recreate them in each target instance. Ask your team to confirm how the repository is hosted, who can read it and how long history is kept, because a DSL file that leaks a prompt can expose business logic even when it holds no keys.
Security risks in moving apps between environments
An exported DSL file carries app logic, prompts and connection structure, so it is a design document as much as a backup. The cards below cover the risks that appear when that file moves from one workspace or instance to another, and the control that should sit in front of each one.
Sensitive logic in prompts and configuration
A DSL file holds prompts, workflow nodes and model parameters in plain YAML. Those can reveal pricing rules, escalation criteria, internal product names or how a review decision is made. Before any file leaves a workspace, have a named reviewer read the prompts and node labels for content that should stay internal, and agree on where approved DSL files are stored. Treat the file as internal documentation, not as a neutral artifact.
Accidental inclusion of credentials
Dify's export excludes third-party API keys, so credentials should not travel in the file. Still, a prompt, a HTTP node header or a custom tool field can contain a literal token pasted during development. Scan each DSL file for key-like strings before it is committed or shared, and make sure the target instance supplies its own credentials. Keep secret handling separate from the export process: SECRET_KEY and the workspace encryption settings protect stored credentials on each instance and do not travel with a DSL file.
Importing into a more permissive workspace
An app that was restricted in a development workspace can become reachable by a wider audience once imported into a shared or production workspace. Member roles, web app access settings and knowledge base visibility are set on the target, not carried by the file. Before import, confirm who can edit, publish and run the app on the target, and review the access configuration after the import completes rather than assuming it matches the source.
Mismatched MCP endpoints
Exported apps reference MCP servers by identifier. If the target workspace has a server with the same identifier that points to a different system, such as a staging or a legacy endpoint, the imported app will call the wrong service and may send data there. Record each MCP server's identifier and the URL it resolves to on both sides, then check the endpoint of every tool the app calls in the target before enabling the app for users.
Unreviewed changes in promoted copies
Once a DSL file is imported, the copy in the target instance can diverge from the reviewed source with no record of who changed what. Edits made in the target, such as a relaxed moderation setting or a changed model, are invisible to the source team. Store each approved DSL file under version control with a reviewer sign-off, and compare the imported app against that file after every promotion so that drift is detected.
Questions teams ask about moving Dify apps
How much effort does a typical Dify app export and import take?
The effort depends on how many apps move, how many of them call tools, MCP servers or knowledge bases, and how much of each app is a complex workflow. A single simple chatflow with no external dependencies is a small task. A set of multi-node workflows that depend on several MCP servers, custom tools and knowledge bases is larger, mainly because each dependency must be recreated and tested in the target workspace. No duration is published for this work, so ask any partner for a written estimate based on your app inventory, and compare it with your own team's time for the same list. Recurring effort is small once the process is documented, but each new app adds its own checks.
Can our team move Dify apps between workspaces without a partner?
Yes, if your team has an administrator who can export and import DSL files, create the matching MCP servers and tools, and re-enter credentials. The Dify app management docs describe the export and import steps, so the mechanics are simple. The harder parts are inventory, identifier matching and testing: knowing every dependency an app uses, confirming the MCP server identifiers match, and checking outputs after import. Teams with a small number of apps and a clear owner for each usually manage this internally. Teams with many apps, strict change control or regulated sign-off often bring in outside help for the review and test steps.
What do we need to provide for an app migration?
Plan to provide four things before work starts:
- Access to the source and target Dify workspaces, with an administrator role that can export apps and create tools.
- Credentials for every model provider, tool and external service the apps use, which you must re-enter because exports do not carry third-party API keys.
- A complete MCP server inventory, listing each server, its identifier, its endpoint and its owner.
- A list of knowledge bases the apps connect to, since the export keeps the connections but not the content, so the content must be recreated or loaded separately.
Confirm the exact access model with your own security team before granting it.
Does the Community edition support promoting apps between workspaces?
Not in the sense of multi-workspace promotion. The Dify pricing page describes the self-hosted Community edition as free and limited to a single workspace. Moving an app between two separate instances, or between two workspaces that require multiple workspaces inside one deployment, is a different case, so confirm with Dify which setup your licence and deployment support. Multi-workspace management, SSO and advanced security are listed on the Enterprise edition, whose pricing is custom. Ask Dify for a written answer before you design a staging and production process around Community edition.
How do Dify upgrades affect DSL file compatibility?
Upgrades can change what an exported DSL file contains or how it is read, so test each import after a version change rather than assuming it works. Dify ships minor releases roughly monthly, so an export taken on one version may need a check on another. Keep the Dify version number in your export records, run a test import on a non-production instance after each upgrade, and review the release notes on the GitHub Releases page for any changes to nodes or tools. Take a backup before every upgrade, as the Docker Compose docs recommend.
Should we keep DSL files under version control?
Yes. A DSL file is plain YAML, so it fits a Git repository, which gives you history, review and a record of what changed before each promotion. Store exports in a repository with restricted access, and never commit credentials, since exports leave out third-party API keys but may still contain prompts or configuration that your policy treats as sensitive. Pair each commit with the Dify version used for the export and a note listing the MCP server identifiers the app needs, so the next import has what it requires.
Do exports include knowledge base content and usage logs?
No. The Dify docs say an export includes app configuration, workflow nodes, model parameters, prompts and knowledge base connections, but not third-party API keys, knowledge base content or usage logs. This means the target workspace needs its own knowledge base data loaded, and the app's historical logs stay in the source instance. Plan the data copy as a separate task, and review whether logs or documents contain personal data before moving them, since that decision follows your own data handling policy.
Where to read the Dify documentation
Before you plan an export or import, read the Dify app management documentation first. It describes how apps are created, edited and exported from the workspace, and it is the reference for what a DSL export actually contains. Use it to confirm the current export behavior for your version, because the page describes the workflow nodes, model parameters, prompts and knowledge base connections that travel in the file, along with the items that do not, such as third-party API keys, knowledge base content and usage logs. Those exclusions set your checklist: every credential, knowledge base dataset and log history must be recreated or migrated by a separate step in the target instance. Treat the page as the baseline for your runbook and record the version of Dify you tested against, since minor releases arrive roughly monthly.
The Dify tools documentation is the second page to read, and it matters most when your apps call MCP servers. Exported apps reference MCP servers by identifier, not by a copy of their connection details, so importing a DSL file into another workspace does not bring the server with it. Read the tools page to confirm how MCP servers are registered, where their identifiers are set, and what must match in the target workspace before the imported app runs. Ask your team to list every MCP server referenced in the exported DSL file, then confirm each identifier can be recreated exactly in the destination, including any authentication settings the server requires. Plan this check before the cutover window, because a mismatched identifier typically surfaces only when a workflow reaches the tool node.
How DeployOpen works on this
DeployOpen treats a Dify app move as a planned change to a self-hosted instance, not a file copy. We scope which DSL content moves, rebuild the parts the export leaves out inside your own infrastructure, and document the result so your team can repeat the move. Engagements are fixed-scope and agreed in writing before work starts.
How we scope
- Inventory the apps, workflows and knowledge base connections that must move, and mark which parts the DSL file does not carry.
- List every MCP server identifier each app references and confirm the matching servers exist in the target workspace.
- Agree in writing which secrets, API keys and knowledge content are recreated by your team and which are handled by DeployOpen.
How we build
- Export DSL files from the source workspace and review them for model parameters, prompts and knowledge base references before import.
- Recreate third-party API keys, MCP servers and knowledge bases in the target instance, then import and reconnect each app to them.
- Test each moved app against the target environment, comparing workflow outputs with the source version on agreed test inputs.
How we hand over
- Deliver a runbook that records the export and import steps, identifier mappings and the credentials your team must supply.
- Store DSL files in a version control repository with a naming convention, commit history and reviewer sign-off for each change.
- Walk your platform and application owners through the handover and the checks to repeat before each future move.
How we support
- Review DSL changes after new Dify releases, since minor releases arrive roughly monthly and can change app configuration.
- Offer ongoing support and upgrades for moved apps as a retainer, scoped to the workspaces and instances you name.
- Confirm with your team which import behaviors and export fields apply to your Dify version before each move.
