Migrate from Contentful to Directus: what moves and what you rebuild
Moving a Contentful space into Directus is a schema mapping and import project plus a permissions rebuild. It is not a file copy. The content engineering team usually owns the work, often with an implementation partner who handles the database, the import scripts and the access model. The Contentful CLI space export gives you the published content model, entries, assets, locales, webhooks and editor interfaces as JSON, and it can download asset files. It does not carry roles or permissions, so every editor group, role and field-level restriction must be recreated in Directus from your current Contentful settings. Plan the effort around the model and the roles, not the size of the export.
Start with the data model. Each Contentful content type becomes a Directus collection backed by a table in your SQL database, and each field becomes a column or a relation, so decide early how references, rich text and localized fields will land. Directus connects to an existing database through the DB_CLIENT setting and supports PostgreSQL, MySQL, MariaDB, Oracle Database, Microsoft SQL Server, SQLite and CockroachDB. Confirm the engine your data residency policy allows before you write the mapping. Run imports against a staging database first, check entry counts per content type against the export, and keep the mapping file in version control so reviewers can see how each Contentful field was translated.
Before committing, clear the license gate. Directus uses the Monospace Sustainable Core License (MSCL-1.0-GPL), which falls outside OSI open source definitions. It allows internal use but bars a Competing Use against Monospace's paid offerings, and each release converts to GPL-3.0 four years after release. Have counsel confirm that your planned use, including any product you build for clients, stays outside the competing-use limit. Read the license history too, since Directus changed its license in April 2023 and again in 2026. Once the gate clears, map each Contentful role to a Directus role, set item-level and field-level rules, and test them with a non-admin account. The native MCP server and AI Assistant follow the same role-based permissions, so any AI tooling inherits what you configure here.
Which Contentful capabilities map cleanly to Directus
This table compares the main Contentful space components with their Directus equivalents and marks each row as clean, needs rework or gap. Read it as a planning list: clean rows carry over with little judgment, rework rows need a design decision before import, and gap rows must be rebuilt by hand because the export does not carry them.
| Contentful capability | Directus equivalent | Status |
|---|---|---|
| Content model (content types) | Collections built from your SQL tables, with fields and relations defined in Studio or the schema | Needs rework |
| Entries | Items in collections, stored in your own database tables | Clean |
| Assets and asset files | Files managed in the Directus file library, stored on your chosen storage adapter | Clean |
| Locales | Translations through a field-level translations model, configured per collection | Needs rework |
| Rich text fields | Plain text, Markdown or WYSIWYG fields that need your own transform from Contentful's document structure | Needs rework |
| References and links between entries | Many-to-one, one-to-many and many-to-many relations on your tables | Needs rework |
| Webhooks and webhook logic | Flows and webhooks configured in Directus; Contentful webhook payloads and conditions must be rewritten | Needs rework |
| Editor interfaces | Field interfaces and layouts in Studio, rebuilt per collection | Needs rework |
| Roles and permissions | Roles and item-level permissions in Directus; not in the Contentful export and must be rebuilt by hand | Gap |
| Content delivery API | REST and GraphQL APIs generated from your database schema, with permissions applied | Clean |
| Hosting and data location | Self-hosted with Docker against your own SQL database, or Directus Cloud | Clean |
What the Contentful export carries and what you move by hand
The Contentful CLI space export gives you the content itself in a portable form, but it does not give you access control or the systems around the space. Read the cards as two lists: what arrives as data, and what you must recreate or re-point before Directus serves a live site.
Content model and locales
The export carries the published content model, including content types, fields and locales. Use it as the blueprint for Directus collections and fields, since each Contentful content type becomes a table in your SQL database. Check that the export reflects the published model rather than unpublished draft changes, and confirm how your locale codes map to the translation fields you plan to create in Directus.
Entries and linked references
Entries arrive as JSON with their field values and links to other entries and assets. Linked references are stored as IDs, so you must resolve them into relations between Directus collections in a second pass. Rich text fields are structured documents, not HTML, so decide early whether they become JSON fields or are converted to Markdown during import.
Assets and asset files
The export lists assets as JSON and can download the files themselves. Confirm that the downloaded binaries are complete, because embargoed or restricted assets may need a token with access to the space. Store the files in Directus file storage or your own object store, then rewrite asset references so entries point to the new file records.
Roles and permissions must be rebuilt
The export does not include roles or permissions, so every Contentful role, environment restriction and field-level limit must be redesigned as Directus roles and policies. Start from a list of who edits, who publishes and who only reads, and map that list to Directus permissions before you import any content. Test each role with a non-admin account.
Webhooks and build hooks
Webhooks in the export describe Contentful's outbound calls, but they do not reconnect anything in Directus. Frontend build hooks, cache purges and preview triggers must be recreated against Directus events and flows, and their endpoints and secrets must be reissued. List every consumer of a Contentful webhook before cutover so none stops publishing silently.
Search indexers and editor extensions
Search indexers, sync jobs and any editor interfaces built for Contentful must be reconnected or replaced by hand. Editor interfaces are stored in the export as configuration, but custom UI extensions run as separate code and are not transferred. Ask each team owning a search index or a custom editor to confirm the new data path before you retire the Contentful space.
The migration sequence from inventory to decommission
The sequence moves a Contentful space into Directus in controlled stages, so each step produces a reviewable artifact and the team can roll back at any point before Contentful is switched off. Every stage ends with a check the team signs off, not just a completed script.
Inventory content types, locales and integrations
The content owner and a developer list every content type, field, locale, reference, webhook, editor interface and asset class in the space, then record which consumers call the delivery API and which roles exist. Contentful's export covers the content model, entries, assets, locales and webhooks, but roles and permissions are not included, so the role matrix must be documented by hand from the Contentful web app. The output is an inventory workbook that both the content and engineering leads sign off before any mapping starts.
Map content types to Directus collections
Decide which SQL database Directus will connect to and set DB_CLIENT accordingly, choosing among PostgreSQL, MySQL, MariaDB, Oracle Database, Microsoft SQL Server, SQLite and CockroachDB. Then map each Contentful content type to a table, each field to a column or relation, and each reference to a foreign key, and note where rich text, localized fields and linked entries need a transformation rule. The output is a schema mapping document with one row per field and an open-questions list for the content owners to resolve.
Build the import scripts and transformations
Developers write repeatable scripts that read the JSON from the space export, convert rich text and entry links into the target format, download asset files, and write rows through the Directus API or directly into the database where the schema is fixed. Scripts run against a staging database built from the mapping document, never against production. The output is versioned scripts in a repository and a short runbook describing the order of operations, so a second run produces the same result.
Run a pilot import on one content type
Import one representative content type, including its linked entries, localized fields and assets, into a staging Directus instance. The content owner then checks a sample of records in Directus Studio against the original entries in Contentful, and the team confirms that assets resolve and that permissions set in Directus behave as the role matrix requires. The output is a pilot reconciliation report listing counts, mismatches and fixes, which becomes the template for the full import.
Import the full space and reconcile
Run the tested scripts against the full space in a staging environment, then compare record counts per content type and locale, check reference integrity, and verify that every asset file is present and linked. Rebuild roles, policies and API tokens in Directus from the role matrix and confirm the REST and GraphQL responses match the shape the front end expects. The output is a full reconciliation report and a rollback plan that names the steps to revert the staging and production databases if a cutover fails.
Run both sources in parallel
For a defined period agreed by the team, editors keep working in Contentful while the import is repeated on a schedule, or the team runs writes into both systems with a clear owner for each content type. Engineers compare delivery output from the two systems, watch error rates and latency, and log every content discrepancy. The output is a parallel-run log and a list of open defects, with exit criteria that the sponsor agrees in writing before cutover.
Cut over the delivery API
Point the front end and any webhooks or build triggers to the Directus endpoints, switch editors to Directus Studio, and freeze writes in Contentful for the final import delta. The team verifies production responses, caching and preview behavior, and keeps the rollback plan ready to repoint traffic. The output is a signed cutover checklist with the timestamp, the owner of each check and the result of the first production content publish.
Decommission Contentful after a retention window
Once the exit criteria hold, export a final full backup from Contentful and store it under your own retention policy, revoke API keys and remove members, and then retire the space according to your contract terms. Confirm the license obligations for Directus, including the Monospace Sustainable Core License's competing-use limit, are recorded with your legal team. The output is a decommission record listing the archived export, the revoked credentials and the license review.
How Directus sits on your SQL database and where the license limit applies
Directus does not replace your database with its own store. It connects to an existing SQL database, and the DB_CLIENT setting selects the engine. The documented options are PostgreSQL, MySQL, MariaDB, Oracle Database, Microsoft SQL Server, SQLite and CockroachDB, according to the Directus database configuration documentation. In practice this means the content tables, system tables and any attached assets metadata sit in a database you provision, back up and restore with the tools you already run. Before migration, confirm with your DBA which engine and version your standards allow, how the database is backed up, and whether Directus can reach it from your network segment. Entries from the Contentful export land in tables you design, so the schema decisions made during mapping become your long-term database design.
The license is the constraint that most needs a decision before you commit. Directus is licensed under the Monospace Sustainable Core License (MSCL-1.0-GPL), not an OSI-approved open source license. According to the Directus license file and directus.com/license, the license permits any use except a Competing Use against Monospace's paid offerings, so internal use of Directus to run your own content operations is the case it is written to allow. Each version converts to GPL-3.0 four years after release. Read the definition of Competing Use closely if you plan to offer Directus-based hosting or content services to third parties, or to customers who compete with Monospace's products.
The license has also changed. The directus/directus commit history shows that the license file moved to BSL-1.1 in April 2023 and was replaced by the Monospace Sustainable Core License in 2026. Versions you deploy are governed by the terms attached to the version you install, so record the exact release tag and license text in your migration record. Have your counsel review the MSCL terms against your specific use case, including any agency, partner or affiliate access, and any plans to resell or embed the platform. DeployOpen can prepare the deployment and documentation, but it does not give legal advice on license interpretation.
What drives the cost and duration of this migration
This table lists the factors that move the cost and schedule of a Contentful to Directus move, with the reason each one matters and how to keep it under control. Read it before asking for a fixed-scope quote, because most of the spend sits in schema mapping, asset handling and the permission rebuild rather than in the software itself.
| Driver | Why it changes cost or effort | How to keep it down |
|---|---|---|
| Number of content types and fields | Each content type becomes a SQL table or collection with its own fields, so every extra type adds mapping, testing and Studio configuration. | Audit the export's content model first and retire unused types before mapping starts. |
| Rich text and reference complexity | Contentful rich text and linked entries must be converted into a shape Directus relations and your frontend can read, which often needs custom transformation code. | Decide early which rich text fields stay as structured JSON and which become plain text or Markdown. |
| Asset volume and file size | Asset files are downloaded from Contentful and uploaded to your storage, so transfer time, storage and checksum verification scale with the library. | Remove stale assets before export and confirm which embargoed or restricted assets need separate handling. |
| Locales and localized fields | Each locale multiplies field values, and Directus translation patterns must match what your sites already query. | List active locales and fallback rules in writing before import begins. |
| Role and permission rebuild | The CLI space export does not carry roles or permissions, so Directus roles, policies and field-level access must be designed and tested from scratch. | Map existing Contentful roles to a short list of Directus roles and test each one with real accounts. |
| Integration and webhook count | Webhooks, build triggers, search indexes and frontend consumers must be repointed to the new Directus API endpoints and tested. | Inventory every consumer of the Contentful API and webhook before scoping the work. |
| Preview, publishing and workflow | Draft states and scheduled publishing in Contentful need equivalent setups in Directus, which can add design and testing time. | Agree the publishing workflow with editors before building content flows. |
| License review | Directus is under the Monospace Sustainable Core License, so legal review of the competing-use limit can add time before the project starts. | Obtain written legal sign-off on your intended use before the fixed-scope quote is signed. |
| Hosting and database operations | Your SQL database, backups, Docker or Directus Cloud hosting, and upgrades are recurring costs that Contentful previously covered. | Ask for the database, backup and upgrade plan as separate line items in the quote. |
What usually goes wrong and how to prevent it
Most Contentful-to-Directus migrations stall on a handful of predictable gaps: assets, access rules, drift during parallel running, content references and licensing. Each card names one failure and the check that catches it before cutover.
Embargoed assets left behind
The space export can download asset files, but assets that are embargoed or access-restricted may not come down with a plain export. Records then point at files that never reached your storage, and the gap shows up only when editors or the frontend request them. Before cutover, list every asset in the export, compare the count of downloaded files against the count of asset records, and re-run downloads for any that failed. Keep a reconciliation report with the migration log.
Roles missing after import
The Contentful export carries the content model, content, assets, locales, webhooks and editor interfaces, but it does not carry roles or permissions. A fresh Directus instance therefore starts with no access rules, which can expose content to the wrong users or lock editors out. Write the role matrix from Contentful's space membership settings before import, recreate roles and field-level permissions in Directus, and test each role with a real account against the REST and GraphQL endpoints.
Schema drift during parallel running
Many teams keep Contentful live while Directus is tested, and editors keep changing content types in the meantime. Any field added in one system and not the other makes the two diverge, and the next re-import silently overwrites or drops data. Freeze content model changes during the parallel window, or log every change in a shared change record and apply it to both systems. Diff the schemas on a fixed schedule until cutover.
Rich text and reference breakage
Contentful stores rich text as structured JSON and links entries by ID, while Directus stores fields and relations in SQL tables. Embedded entry links and asset references can point to IDs that no longer exist after import, and rich text nodes may not map cleanly to Directus field types. Build an ID mapping table during import, rewrite references in a second pass, and render a sample of pages from each content type to find broken links before the frontend switches over.
Database ownership and backups
Because Directus sits on your own SQL database, its uptime, backups and point-in-time recovery become your responsibility from the first import. Teams often treat the import as a one-time script and skip backup testing on the database that now holds the only copy of the content. Confirm which engine you will run, set and test restore procedures, and keep the Contentful export as a read-only archive until the new system has been restored from backup at least once.
License surprises discovered late
Directus is not under an OSI open source license. It uses the Monospace Sustainable Core License, which allows internal use but bars a Competing Use against Monospace's paid offerings, and each release converts to GPL-3.0 four years after release. Legal review often happens after build work, when the business model of a product or agency service may conflict with the license. Have counsel read the license text against your planned use before committing, and record the decision in your architecture file.
How the migration changes by starting point
A single space with a handful of content types and modest asset volume is usually the simplest starting point. The export gives you one JSON set to map, one schema to recreate as Directus collections, and one database to stand up. Most of the effort sits in deciding how Contentful references and rich text become relational fields in your own SQL tables, and in checking that Directus Studio meets the needs of the editors who will use it every day.
- Schema mapping: Map each content type to a table and each field to a column or relation, then review the mapping with one or two editors before importing anything.
- Assets: Download the asset files with the export and decide where they live, such as your own object storage, since the export does not replace a file store.
- Roles: Rebuild the few roles you use in Directus by hand, because the export does not carry roles or permissions.
- Cutover: A short content freeze is often enough, so plan one import run and one rehearsal.
- Licensing check: Confirm the MSCL terms against your intended use before you build anything on top of Directus.
Before starting, confirm which webhooks and integrations depend on the space and whether anything beyond the front end reads from it.
Enterprises often run several spaces, each with its own content model, environments, locales and editorial teams. Here the work shifts from importing one dataset to designing a shared data model in your SQL database that serves every brand or region without forcing them into one structure. Sequencing matters more, and the cutover usually has to be staged space by space.
- Shared model decisions: Decide which content types become common tables and which stay separate per brand, since this choice drives every later permission rule.
- Locale mapping: Confirm how each Contentful locale and its fallback chain maps to your Directus structure before writing any import script.
- Staged cutover: Move one space at a time, keeping dependent references and redirects working between stages.
- Role design: Expect a larger role and policy set, built and tested against real editor accounts, because the export carries none of it.
- Environment parity: Confirm how staging, preview and production databases are kept in step.
Ask the implementation partner and your security team to agree on the shared model and the staging order in writing before the first import, so the scope and dependencies are documented.
Some teams cannot switch off Contentful on day one. Downstream systems, archived pages or legal retention may still need to read from the old space for a period. In this case the migration runs in parallel: Directus becomes the system of record for new edits, while Contentful stays available for reads until the dependent consumers move. The sequence and the synchronization rules become the main design work.
- Direction of truth: Decide which system wins for each content type during the overlap, and write that rule down so editors know where to edit.
- Sync or re-export: Choose between a repeated export and import cycle and a live integration, and confirm the cost and maintenance of each with your team.
- Consumer inventory: List every application, feed and webhook still reading Contentful, because each one must be moved or retired before the read source can end.
- Read-only period: Agree a date for disabling edits in Contentful, separate from the date the subscription ends.
- Retention: Keep a verified archive of the final export for records your organization must hold.
Confirm with Contentful how your subscription and API access behave during the overlap, since the terms define how long you can keep reading without a plan change.
Questions buyers ask before moving from Contentful to Directus
How much does moving from Contentful to Directus cost?
No supplied fact gives a price for this migration, so the figure depends on scope and your environment. The cost has three parts: the one-time migration work (schema mapping, importing entries and assets, rebuilding roles and frontend changes), the infrastructure you run (database, file storage, hosting, backups, CDN), and the people who operate and upgrade Directus. Ask for a quote that lists these separately, states what is one-time and what recurs, and names who pays for each line. Drivers include the number of content types, locales, rich text fields with references, the volume of assets, and how many integrations depend on Contentful's API.
How long does a Contentful to Directus migration take?
No supplied fact gives a duration, so treat any timeline as provisional until scope is written down. The main variables are how many content types and fields the space has, whether the frontend must be rebuilt against Directus's REST or GraphQL APIs, how much content needs manual cleanup, and how quickly your team can review each stage in a staging environment. A fixed-scope agreement with written deliverables and a timeline is the usual way to pin this down before work starts.
What does our team need to provide for the migration?
Plan to supply people who know the content model and the frontend, plus access to infrastructure. In practice that means a named owner for the content model, an engineer who understands how the frontend queries Contentful, access to the Contentful space with rights to run the export, a target SQL database and hosting account, and someone who can approve content that needs editing after import. Ask the implementer to list each of these as a dependency in the written scope so gaps surface early.
Can our own team do the Contentful to Directus migration without an implementation partner?
Yes, a capable team can do it, provided it has skills in SQL schema design, scripting against the Contentful export JSON, and operating Docker or an equivalent container host. The Contentful CLI can export a space's content model, content and assets as JSON and download asset files, so the export itself is straightforward. The harder parts are mapping linked entries to foreign keys, rebuilding roles, and testing the frontend. Many teams split the work: they keep content ownership in-house and bring in outside help for the mapping, security hardening and cutover.
Does the MSCL license let us use Directus for our own business?
Internal use is permitted under the Monospace Sustainable Core License 1.0 (MSCL-1.0-GPL), which bars only a Competing Use against Monospace's paid offerings. Running Directus to power your own websites, apps and internal tools is generally a different category from offering a competing hosted service, but the exact boundary belongs to your counsel to confirm. Read the license text at the Directus license page and the repository license file, check whether your plans include reselling Directus as a service, and record the version you deploy because each release converts to GPL-3.0 four years after release. Note that Directus is not an OSI open source license.
What happens to roles and permissions when we export from Contentful?
Roles and permissions are not included in the Contentful CLI space export, so they must be rebuilt in Directus. Memberships and user accounts also need to be recreated rather than copied. Start by listing the roles your editors and developers hold in Contentful, then map each to a Directus role with explicit permissions on collections and fields. Directus generates its REST and GraphQL APIs from the database schema, and its native MCP server and AI Assistant follow the same role-based permissions as human users, so review those permissions with the same care. Ask any implementer to include a permission test matrix as a deliverable.
Where does the content live after the migration, and who runs the database?
Directus connects to an existing SQL database through its DB_CLIENT setting and supports PostgreSQL, MySQL, MariaDB, Oracle Database, Microsoft SQL Server, SQLite and CockroachDB. Your team, or the partner you hire, runs that database, its backups, upgrades and access controls, so these become operational responsibilities that Contentful previously carried. Confirm which database engine your standards allow, where backups are kept, and who is on call for the Directus deployment. Directus can also run on Directus Cloud, which changes who operates the hosting but not the license terms you need to check.
How DeployOpen scopes and runs a Contentful to Directus migration
DeployOpen plans, implements, integrates, hardens, backs up and documents self-hosted Directus inside your own infrastructure, whether that is your cloud account, a data center or an air-gapped network. The work covers the pieces this page describes: the SQL database Directus connects to through its DB_CLIENT setting, the mapping of Contentful content types to tables, the import of entries and assets from the space export, the rebuilt role and permission model, and the Docker deployment that runs Directus Studio and its REST and GraphQL APIs. Most engagements are fixed-scope, so the scope, deliverables and timelines are agreed in writing before any work starts. A quote follows from that written scope, which means the first useful step is a written description of your content model, your locales, your asset volume and the roles your editors and developers use today.
Expect the cost to fall into a few components: who designs the table mapping, who writes and runs the import scripts, who provisions and hardens the database and hosting, who rebuilds roles and permissions, and who owns backups and upgrades afterward. Ask any implementation partner, DeployOpen included, to split the quote along those lines so you can see which parts are one-time and which recur. Ongoing support, upgrades and continuous testing are available as retainers, and those are usually the recurring line. DeployOpen does not publish a price list, and it is not an official partner, reseller or certified provider of Directus. Before you sign anything, confirm the Directus license terms for your use case with your legal team, since the Monospace Sustainable Core License is not an OSI open source license.
