I want to customize the maintenance page in Drupal 8.

How do I theme it?

  • Even for self-aswered question the general advises for asking a question are valid. As it is, this question is too broad: It doesn't even describe the issue you are having.
    – apaderno
    Mar 29, 2016 at 8:02

1 Answer 1


In Drupal 8, settings.php contains the following line:

# $settings['maintenance_theme'] = 'bartik';

First, uncomment this setting and change "bartik" to the machine name of your custom theme.

Next, copy the core maintenance template core/modules/system/templates/maintenance-page.html.twig to templates/maintenance-page.html.twig in your custom theme directory.

Lastly, flush the Drupal cache to enable your new maintenance page template. If you need alter the template's variables, you can add the MYTHEME_preprocess_maintenance_page() to your *.theme file.

  • 1
    The settings.php says "This applies when the site is explicitly set to maintenance mode through the administration page or when the database is inactive due to an error." However, on my site this only works if I turn on maintenance mode. If I intentionally break access to my database by changing the password I get a page with a PDO error, not my maintenance page
    – nexus_6
    Jul 28, 2016 at 10:26
  • When doing doing this, the changes are displayed on the update page after installing a module. Is the process that creates the update page use the maintenance page twig? maintenance-page.html.twig
    – mike_kc
    Oct 2, 2018 at 15:46
  • Not sure if this became available in later versions, but when creating my own custom maintenance page, I found I didn't need to update settings.php to register it.
    – karolus
    Oct 9, 2018 at 15:36
  • In addition, since maintenace page don't always want to respect the theme's HTML, I created a suggestion in "template_theme_suggestions_html_alter.php" by adding this piece of code in it : if(\Drupal::state()->get('system.maintenance_mode')){ $suggestions[] = 'html__maintenance'; } Jan 9, 2019 at 10:14
  • @nexus_6 I know this is a late reply, but I found this page which may explain why the maintenance page doesn't kick in when the DB is offline. It look like it is an active bug that has persisted through Drupal 9: drupal.org/project/drupal/issues/2720109
    – pmagunia
    Jan 6, 2021 at 20:16

Not the answer you're looking for? Browse other questions tagged or ask your own question.