Upgrading Directus from v10 to v11: A Safe and Reliable Guide

When I first learned I'd be upgrading Directus, I felt a familiar mix of confidence and apprehension. Having upgraded packages before, I knew the general process, but Directus is different. Schema changes, dropping outdated fields, or not typing them in are potential issues with CMS upgrades. As I dove into the upgrade process, I quickly realized this wasn't just another package update. The extra steps, like backing up the database first reminded me that production upgrades require a different mindset than development work. The local upgrade went smoothly, which gave me a false sense of security. Then came the deployment headache. Nixpacks refused to build with the Node.js version specified in our engine, and that's when the real challenge began. What started as a routine upgrade turned into a day-long puzzle that required creating a custom nixpack file. By the end, I felt both exhausted and accomplished. The upgrade pushed me to understand deployment infrastructure in ways I hadn't before, turning what could have been a simple package update into a valuable learning experience about production deployment complexity.

Important: Directus 11 Requires Node.js ≥ 22

Before starting the upgrade, make sure your local and deployment environments are running Node.js version 22 or higher.

Check your Node version:

node -v

If it's lower than 22, upgrade Node before proceeding. We recommend using a version manager like nvm or asdf:

nvm install 22.12.0
nvm use 22.12.0

Set Node version in package.json

To ensure your deployment environment (e.g., Railway, Vercel, Netlify) uses the correct version, update your package.json:

"engines": {
  "node": ">=22.12.0"
}

Watch for breaking changes in dependencies

Upgrading Node may break other packages in your project. After switching Node versions, run:

# NPM
npm install

# OR Yarn
yarn install

And resolve any errors or dependency issues before proceeding.

Example Error You Might See If Using Node < 22

The engine "node" is incompatible with this module. Expected version ">=22.12.0". Got "18.20.4"
error Found incompatible module.

Step 1: Review Breaking Changes

Before upgrading, it’s critical to review all breaking changes, not just those in the most recent version.
Review the Directus breaking changes to catch:

• Field and API behavior changes
• Role/permission updates
• Any deprecated features or schema tweaks
• Core system architecture changes
• Extension/plugin compatibility notes
• Auth and API adjustments

Understanding what changed ensures you're not caught off guard after the upgrade.

Step 2: Prepare a Local Testing Environment

To avoid surprises in production, create a local copy of your staging (or production) environment.

Clone the staging environment:

• Export the current database
• Copy your .env
• Pull your current Docker setup (if applicable)

# Example: Export DB
pg_dump -U your_user -h staging-db-host your_db > staging_backup.sql

Step 3: Backup Everything

Always take a backup of your database before any major upgrade.

Whether you're working locally or pushing to staging, never upgrade without a clean rollback plan.

Step 4: Upgrade the Directus Version

Update your Directus package to version 11.10.0.

If using NPM/Yarn:

# NPM
npm install directus@11.10.0

# OR Yarn
yarn add directus@11.10.0

If using Docker:

If you are self-hosting or using Docker for your build, this step is important.
Update the Dockerfile or docker-compose.yml to use either V11.10.0 or the latest image:
v11.10.0:

services:
  directus:
    image: directus/directus:11.10.0

Latest:

services:
  directus:
    image: directus/directus:latest

Then rebuild:

docker-compose build
docker-compose up

Step 5: Run Migrations Locally

After upgrading, run the Directus migration command only in your local environment to apply any necessary schema changes and confirm your data structure is still intact:

npx directus migrate:latest

Note: On staging and production, migrations will run automatically during deployment, so no need to run this manually there.

Step 6: Test Everything Locally

Before deploying, verify your project works as expected:

• Log in to the Admin Panel
• Verify collections, fields, and relationships
• Run common API queries
• Test filters, roles, and permissions
• Check custom endpoints or hooks
• Confirm plugins or extensions still work

This helps you catch breaking issues before they hit your users.

Step 7: Deploy to Staging, Then Production

Once everything checks out locally:

1. Deploy to your staging environment
2. Verify everything again in staging
3. Then deploy to production

Optional: Clean Up

After deployment:

• Update your internal documentation
• Remove deprecated config or unused fields
• Ensure backup schedules are still intact

You're Done!

Enjoy the performance improvements, new features, and better developer ergonomics! Need help upgrading? Reach out and schedule a call today!

Resources

• Directus Documentation
• Nixpacks Documentation