Is it Time to Upgrade to Drupal 11?

A collage featuring a laptop with the Drupal 11 logo and a figure seated on the screen, symbolizing digital innovation.

With the release of version 11, Drupal continues its steady evolution toward a more modern, performant and developer-friendly future. This latest version introduces a set of meaningful improvements – from better support for decoupled architectures to simplified theming and performance gains – that could have a direct impact on how efficiently your team delivers and maintains digital experiences.

If you're currently running a Drupal 10 site, you need to start thinking about upgrading to Drupal 11 – and we’ve got you covered here. We’ll walk you through the key enhancements in Drupal 11, what to assess before moving forward and how to carry out a smooth upgrade with minimal disruption.

Key features in Drupal 11

Single-directory components (SDCs)

Single directory components is perhaps the most transformative feature in Drupal 11, achieving stable status in the core platform. Let’s unpack what it is.

A component is a reusable piece of the user interface (UI), like a button, header, product card or contact form. Each component has three main parts:

  • HTML for structure (what it looks like).
  • CSS for styling (colors, fonts, layout).
  • JavaScript for interactivity (animations, form validation).

Before Drupal 11’s SDCs, these files were scattered across different folders in a Drupal theme. For example, your button’s HTML might be in one folder, its CSS in another and its JavaScript somewhere else. This made it hard to find and manage everything, especially on big projects.

SDC solves this problem by putting all the files for a component into one folder. Here’s a simple example for a "call-to-action button" component:

call-to-action-button/  

├── call-to-action-button.twig (HTML structure)  

├── call-to-action-button.css (styling)  

├── call-to-action-button.js (interactivity)  

└── call-to-action-button.yml (metadata/config)  

As you can probably tell, SDC brings Drupal in line with modern tools like React or Vue.js, which also use components. The benefits of this include:

  • Simplified theming workflow – Drupal automatically detects and loads the component’s CSS/JS when the component is used. No extra setup needed!
  • Reduced learning curve – you don’t need to memorize where files go. Just create a folder and add your component’s files.
  • Reusability – once you create a component (like a newsletter signup form), you can reuse it anywhere on your site without rebuilding it from scratch.
  • Consistency – changes to the component (e.g., updating a button’s color) automatically apply everywhere it’s used.
  • Future-proofing – SDC prepares Drupal for upcoming features like Layout builder (both blocks and sections), automatic forms and storybook compatibility.

Workspaces

The Workspaces module is now stable in Drupal 11 – a significant advancement in Drupal's content governance capabilities. It provides users with sophisticated content staging and workflow management capabilities by enabling content teams to edit and prepare content in multiple environments without affecting live websites. Users can stage, preview and publish multiple content items simultaneously, making it particularly valuable for organizations managing large-scale content updates or time-sensitive campaigns.

Recipes

Recipes (experimental) are pre-packaged toolkits that add ready-to-use features to your Drupal website to instantly add things like:

  • A blog section (with posts, categories and comments).
  • An event calendar (with registration forms and reminders).
  • A photo gallery (with grids, slideshows and filters).

Unlike older Drupal tools (which often required technical expertise), recipes let you mix and match features easily. So, if you want a blog and a store, just apply both recipes.

At DrupalCon 2024, Dries Buytaert (Drupal’s creator) showed how a recipe could add a full event-management system to a site by installing modules, applying configuration and publishing default content in under a minute – something that previously took hours. Not to mention, recipes are a key part of Drupal Starshot (now called Drupal CMS) – a new initiative to make Drupal as easy to use as WordPress or Wix.

Symfony 7 and PHP 8.3+

Drupal 11 incorporates Symfony 7 as its underlying framework, replacing Symfony 6 and bringing significant performance, security and capability improvements. This includes improved routing performance, service compilation optimizations and reduced loading times through enhanced cache routing mechanisms.

Additionally, Drupal now requires PHP 8.3, which brings substantial performance improvements at the runtime level, like improved memory management, faster function execution and enhanced opcode caching capabilities. This results in measurably faster page response times and reduced server resource consumption.

PHP 8.3 also introduces enhanced support for modern performance optimization techniques, including improved just-in-time (JIT) compilation, which can significantly accelerate PHP code execution for computationally intensive operations.

Expanded accessibility compliance

Drupal 11 continues the platform's tradition of prioritizing accessibility as a fundamental principle rather than an afterthought . The Drupal community has committed to ensuring that all features align with the World Wide Web Consortium (W3C)'s Web Accessibility Initiative (WAI) guidelines, specifically targeting WCAG 2.2 AA compliance. This represents an advancement from previous versions that focused on WCAG 2.1 AA standards.

The platform treats accessibility barriers as bugs rather than feature requests, a philosophy that has been central to Drupal's development since version 7 . This approach means that accessibility issues can actually block Drupal releases if they fail to meet the established accessibility gate requirements.

New admin navigation

Drupal’s admin toolbar remained largely unchanged since Drupal 7, leading many sites to install contrib modules like Admin Toolbar or switch to custom themes like Gin to compensate for deep-linking and usability gaps.

Thankfully, Drupal 11 introduces a new admin navigation system via the experimental Navigation module, replacing the old horizontal toolbar with a modular, vertically oriented layout that is extensible, keyboard-friendly, and optimized for large content teams. This design aims to reduce click depth, streamline daily administration, and lay the foundation for future features like the Experience Builder and Project Browser.

The vertical sidebar supports multiple levels of nested menus, is fully customizable, and supports modern design tokens for light/dark modes and compact views. The top bar has also been reworked to move contextual actions, like entity tabs, into a sticky dropdown for easier access.

With the new navigation system, site builders can easily manage and customize blocks via a drag-and-drop interface, offering better control over how the sidebar appears. The system also includes density and mode controls, allowing administrators to switch between different padding presets and enable dark mode.

Step-by-step guide to upgrading from Drupal 10 to Drupal 11

Pre-upgrade preparation

Before making any changes, make sure to:

  • Set up a local/staging environment: Never upgrade directly on a live production site. Instead, clone your site to a local or staging environment. This includes copying the database and files. This isolated environment lets you test the upgrade without impacting real users. If you must run the upgrade on production, put the site in maintenance mode first to prevent content changes during the process.
  • Verify environment requirements: Drupal 11 has updated system requirements, so ensure your environment meets them before upgrading:
    • PHP: Upgrade PHP to 8.3.
    • Database: Use MySQL 8.0+, MariaDB 10.6+, PostgreSQL 16+, SQLite 3.45+. If not possible yet, you’ll need a MySQL 5.7/MariaDB 10.3 backport module as a temporary workaround.
    • Drush: Update Drush to version 13, which is compatible with Drupal 11. You can require this via Composer (e.g. composer require drush/drush:^13).
    • Web server: Drupal 11 no longer supports Microsoft IIS out of the box. Ensure you’re using a supported web server (Apache 2.4.7+ recommended).
    • Composer: Make sure you have an updated Composer (2.x) to handle modern Drupal dependencies.
  • Update to the latest Drupal 10 (minor version): Before jumping to Drupal 11, bring your Drupal 10 site up to the latest 10.x release (at least Drupal 10.3.0 or newer) using the following command: composer require drupal/core-recommended:^10.3 --update-with-all-dependencies

Now that we’ve got the foundational requirements out of the way, it’s time to start the actual upgrade process from Drupal 10 to 11:

Step 1: Compatibility checks for core, contributed and custom modules/themes

The biggest challenge in upgrading is ensuring that all code (modules, themes, custom code) is Drupal 11-compatible.

First, review deprecations with the Upgrade Status module: This tool scans your system and reports:

  • A list of contributed modules and whether a Drupal 11-compatible release exists.
  • A report on deprecated API usage in your custom modules/themes.

If your site is using any deprecated core modules (like Actions UI, Tracker, Book, Forum, Statistics, Tour, etc), you might want to: 

  • Uninstall those modules on Drupal 10 to avoid errors later if the functionality is not actually used. 
  • Check for contributed replacements if you need the functionality. In most cases, the deprecated core module has been “ported” to a contributed module available on Drupal.org. For instance, the Book and Forum modules can be added back as contributed projects that work on Drupal 11. Install those on Drupal 11 after the core update to retain functionality. 
  • Use the Drupal Rector tool to automatically fix many deprecated API uses in your custom code. Run it on your custom module code to generate patches that replace deprecated calls with their Drupal 11 equivalents. It will also flag any remaining to-do items in comments that need manual attention.

Now, update contributed modules and themes: Bring all contributed projects (modules and themes from drupal.org) up to their latest versions while still on Drupal 10. Check each project’s page for a Drupal 11-compatible release or notes. 

Run the following to see available updates:

composer outdated "drupal/*"

For each project with updates, run:

composer require drupal/PROJECT_NAME:^x.y

Substitute x.y with the latest release.

Step 2: Adjust file permissions

With backups made and code made compatible, you can proceed to update the Drupal core itself using Composer. Composer will handle downloading Drupal 11 core and updated dependencies.

If you are using a Drupal Project template, the sites/default directory and settings files might be write-protected (read-only). Drupal’s core Composer scaffold may need to update files like settings.php or .htaccess. To avoid permission errors, you can temporarily loosen restrictions (especially on Linux/Mac systems).

chmod 777 web/sites/default

find web/sites/default -name "*settings.php" -exec chmod 777 {} \;

find web/sites/default -name "*services.yml" -exec chmod 777 {} \;

This grants write access so Composer can modify those files if needed (e.g., updating the settings file with new settings or rewriting the services file during scaffold).

This step may not be needed on all projects, but be aware of it if you get “permission denied” errors. Also, remember to restore secure permissions after the upgrade (we will do this in a later step).

Step 3: Update Composer requirements for Drupal core 

Modify your Composer dependencies to pull in Drupal 11 packages. In your project root, run the following Composer require commands (as one combined command or sequentially):

composer require \

  drupal/core-recommended:^11 \

  drupal/core-composer-scaffold:^11 \

  drupal/core-project-message:^11 \

  --update-with-all-dependencies --no-update

This tells Composer to switch to the Drupal 11 series for core packages, including:

  • drupal/core-recommended:^11 – the Drupal core metapackage which pins core and PHP library versions.
  • drupal/core-composer-scaffold:^11 – ensures scaffold files (settings.php, etc.) are updated for Drupal 11.
  • drupal/core-project-message:^11 – updates the post-update message (not critical but part of core’s packages).

If your project uses drupal/core-dev (a package with testing tools), also update it for Drupal 11:

composer require drupal/core-dev:^11 

--dev --update-with-all-dependencies --no-update

This is only if core-dev is listed in your composer.json.

Additionally, update Drush now if you haven’t already. This allows us to set all requirements first (core, core-dev, contrib module updates done earlier, etc.) to avoid dependency conflicts.

Step 4: Run Composer update 

Now, perform the actual update to bring in Drupal 11:

composer update

Composer will resolve dependencies and download Drupal 11 core and any needed updated libraries. This might take some time. If you see memory errors, you can run the following to lift memory limits:

COMPOSER_MEMORY_LIMIT=-1 composer update

Composer will update Drupal core code to 11.x and update various libraries (Symfony will jump to 7, jQuery to v4, etc., as Drupal 11 uses newer dependencies. It will also update contributed modules you specified earlier. Essentially, your vendor folder and core code will be replaced with the Drupal 11 versions.

If the update completes without errors, you have the new core code in place. Proceed to step 5.

If you get errors like “Your requirements could not be resolved to an installable set of packages,” this usually means a module or package isn’t compatible (Composer couldn’t satisfy the Drupal 11 requirement). Examine the error output for lines indicating which package is causing the conflict. For example, you might see a message that a module requires drupal/core ^10 drupal.stackexchange.com. 

In such a case:

  • Remove or update the offending module (as identified in compatibility checks).
  • You can run the following to pinpoint which package is blocking the update: composer why-not drupal/core 11.0.0
  • Use the Lenient Composer Plugin as described earlier to bypass core version checks if you plan to apply a patch.

After addressing the conflicts (updating or removing modules, adding the lenient plugin or patches), run this again: composer update

Step 5: Database updates

After the code is updated, you must update the Drupal database to account for schema changes in core and any module updates. Run the database updates using Drush:

drush updatedb -y –

Alternatively, if not using Drush, use the web interface. Navigate to /update.php in your browser and follow the update wizard. This accomplishes the same thing via a UI.

Skipping this step can leave the site in a broken state (update hooks might add new tables, fields or config needed by Drupal 11).

At this point, before deploying changes to the live site, back up your entire Drupal site (codebase, database, and uploaded files). This ensures that if anything goes wrong during deployment, you can restore the site to its previous state. 

Step 6: Restore permissions

If you loosened file permissions earlier, set them back to secure values now:

chmod 755 web/sites/default

find web/sites/default -name "*settings.php" -exec chmod 644 {} \;

find web/sites/default -name "*services.yml" -exec chmod 644 {} \;

This ensures your settings and services files are read-only to the web server, improving security (the same permissions as before the update).

Step 7: Clear caches

Rebuild Drupal caches to ensure all old cached definitions are removed:

drush cr

This is especially important after a major upgrade to clear out old class definitions, Twig templates, etc. (Note: Drush’s updatedb often clears caches at the end, but an extra cache clear doesn’t hurt).

If you put the site in maintenance mode, you can now disable it.

Step 8 (optional): Configuration export

If you use Drupal’s configuration management (config sync), it’s wise to export the configuration after the upgrade:

drush config:export -y

This captures any configuration changes introduced by the update (for example, core may have new configuration defaults or module updates might add config).

Commit these to your version control. This keeps your config in code up-to-date.

At this point, your code and database are on Drupal 11 – congratulations! The site should be running Drupal 11 core. 

Next, you will need to verify everything works as expected.

Post-upgrade steps: Testing and verification

Perform thorough testing to ensure the site functions correctly:

  • Smoke test the site: Visit the homepage and a few key pages to confirm they render without errors. Log in to the site as an administrator and navigate through the admin pages.
  • Functionality testing: Test all major functionality:
    • Create or edit content (node add/edit forms) to ensure editors still work.
    • Test custom forms or features provided by custom modules.
    • Navigate through menus and test search, contact forms or any interactive features.
    • If you have multilingual content, switch languages to ensure language negotiation still works.
    • Verify any automated jobs (cron tasks) if possible.
  • Theme and front-end: Check that the theme is displaying correctly. Look at styled components, slideshows or JavaScript behaviors to ensure nothing broke with the upgrade (Drupal 11 updates libraries like jQuery, which could affect custom front-end code). If you have a custom theme, ensure its core_version_requirement in the theme .info.yml file allows Drupal 11 (e.g. "^10 || ^11"). This should have been flagged by Upgrade Status earlier.
  • Run automated tests (if available): If your project has PHPUnit or Behat tests, run them now. This can catch regressions in complex functionality. Drupal 11 uses PHPUnit 10, so ensure your tests are updated for PHPUnit 10 compatibility if you have any custom test code.
  • Monitor logs: Check Drupal’s log (recent log messages, use drush watchdog:show or the syslog) for any errors that weren’t obvious in the UI. Also check PHP error logs. Look for PHP fatal errors or deprecation warnings (though ideally, there should be no Drupal deprecation warnings now, since Drupal 11 removed deprecated code). Any unexpected errors should be investigated – they may point to a contributed module that wasn’t fully Drupal 11-ready or a piece of custom code still calling an obsolete API.
  • Verify module functionality: Double-check that each enabled module is functioning. For example, if you have Views, ensure views pages still work. If using Layout Builder, test layout editing. If using media, verify media upload works, etc. Pay special attention to any module that had an update or that you had to apply a patch for.
  • Check custom features: For any custom module or significant custom code, go through its functionality with a fine-tooth comb. If you wrote custom integrations or complex business logic, ensure the outcomes are correct (for instance, if you have a custom payment integration, do a test transaction in a safe environment).
  • Performance sanity check: While not a full load test, observe page load times and any JavaScript console errors. Drupal 11 should not be slow; if you see major issues, there might be an underlying problem to debug (like a caching issue or a module behaving badly).

By the end of testing, you should have confidence that the Drupal 11 site is stable and ready!

Upgrading between major Drupal versions can present challenges. Here are some common pitfalls and how to address them:

Composer dependency conflicts

A frequent issue is Composer refusing to complete the update due to conflicting requirements. This usually stems from a contributed module that hasn’t declared Drupal 11 compatibility. The error will mention a package “requires drupal/core (^9 || ^10)” which conflicts with the ^11 we’re trying to install. 

To fix:

  • Identify the module(s) in question from the Composer error output (it often lists them). For example, language_switcher_langcode requires drupal/core ^10.
  • Update that module to a newer version if one exists (check drupal.org for a Drupal 11 compatible release).
  • If no release is available, consider removing the module before upgrading (if it’s not critical) or replacing it with an alternative.
  • Use the Lenient Composer Plugin for modules that have patches available but no release. This plugin allows Composer to temporarily ignore core version constraints so you can apply patches. Be cautious – use it only for modules you are confident will work with the patch.
  • Use the following to pinpoint which dependency is blocking the upgrade: composer why-not drupal/core 11.x

This command is very helpful when Composer’s error output is long – it will list any package that explicitly prevents Drupal 11 from being installed.

Missing Drupal 11 compatibility in custom code

If you missed any deprecated API usage in custom code, you might encounter fatal errors after update (for example, calling a function that no longer exists in Drupal 11). To resolve, go back to your code and fix the usage (consult the change records on drupal.org for how to update the code).

Also, you can use Drupal’s deprecation error logging. In settings.php, you can temporarily turn on error reporting to see what is failing. However, ideally, the Upgrade Status scan should have caught these. This underscores the importance of running those scans before the upgrade.

Forgot to update to the latest Drupal 10 first

If you skipped updating to Drupal 10.3+ and tried to go to 11, you may run into mysterious issues or update failures. The correct approach is to update to the latest 10.x release first. If you forgot, do not proceed with the Drupal 11 upgrade – first roll back, update Drupal 10, then attempt the upgrade again.

Configuration synchronization surprises

If you use configuration management (config export/import), note that a major upgrade might introduce new configuration. For example, Drupal 11 might have new default config for new features. If you deploy code to production without also deploying config changes, you could see errors about “unmet dependencies” or missing config.

To avoid this, always export config after the upgrade and import it on the target site. This ensures your config is in sync with the new core.

Testing on production data

One pitfall is not testing with a recent copy of production data. Differences in content or configuration between your test environment and production could lead to unexpected issues after deployment. Always test with data that is as close to production as possible (e.g., a recent DB dump), so you catch any issues with real content.

Boost your Drupal experience with Pantheon

Upgrading to Drupal 11 is an exciting move for your site, but to really make the most of all the new features and performance enhancements, you need the right platform backing you up.

Pantheon is built specifically to support Drupal with powerful tools and automation, making things like backups, updates and scaling effortless. Our Dev, Test, Live environments enable you to develop and test changes without affecting the live site available to your users.

Pantheon also takes care of the heavy lifting when it comes to performance optimization. The platform has built-in support for caching and a Global CDN to make sure your site loads fast, no matter where your users are. 

So, if you’re looking to take your Drupal site to the next level, rest assured, Pantheon is the platform that can help you do it. It’s fast, secure and built to grow with your needs, no matter how big or complex your project gets.

Start using Pantheon today and see how easy it is to manage, scale and optimize your Drupal 11 site!

Drupal