Twig Template suggestions and debug

The Twig engine provides options for configuring debugging, automatic reloading (recompiling) of templates, and caching compiled templates in the filesystem. By default, the Twig theming engine compiles templates into PHP code and stores the compiled code in memory. Compiled code is unsuitable for development, since changes in Twig templates are not immediately updated in your Drupal site. Twig cache can be cleared through Drupal's clear cache interface, but for ongoing development it's easier to change Drupal's settings so that Twig doesn't cache anything at all.

Note that in most cases you'll likely want to disable Render API caching as well. Instructions below. If you do not do this you will still need to flush the cache before seeing the changes to your Twig file because when the Render API uses the associated Twig template to generate the HTML it then caches the generated HTML and your Twig template isn't used on subsequent page views. Regardless of Twig debug settings.

How to enable debugging with Drupal Console


drupal site:mode dev

This will change the following values in your sites/default/services.yml:


twig.config: { debug: true }

You should see something similar to this:


How to enable debugging manually

  1. Locate your site's services.yml file, likely located in sites/default/services.yml
  2. If services.yml does not yet exist; copy and rename it to services.yml.
  3. Edit the services.yml file and enable one or more of the debugging options defined below.
  4. Rebuild cache.

Locate the twig.config parameters in your services.yml and make changes there. Example:


    debug: true

Twig debugging options

debug: true
When debugging is enabled:

  • The markup of each Twig template is surrounded by HTML comments that contain theming information, such as template file name suggestions.
  • Note that this debugging markup will cause automated tests that directly
    check rendered HTML to fail. When running automated tests, 'twig_debug'
    should be set to FALSE.
  • The dump() function can be used in Twig templates to output information
    about template variables.
  • Twig templates are automatically recompiled whenever the source code
    changes (see auto_reload below).
  • Not recommended in production environments (Default: false).

Twig auto-reload

auto_reload: true

  • Automatically recompile Twig templates whenever the source code changes. If
    you don't provide a value for twig_auto_reload, it will be determined based
    on the value of twig_debug. Unless you specifically want auto_reload and NOT debug, you don't need to touch this setting. Just enable debug.
  • Not recommended in production environments (Default: null).

Twig cache

cache: false

  • Unless you have a specific use case, do not disable the Twig cache. When you enable Twig debug (or just auto_reload if for some reason you don't want to enable debug) the Twig cache won't get in your way. Disabling the Twig cache will only make for a slower development experience because each template would need to be compiled regardless of whether it's been edited or not. Also, you can't easily look at or debug the compiled Twig templates (PHP classes, by default in sites/default/files/php/twig) if they are not cached to disk.
  • By default, Twig templates will be compiled and stored in the filesystem to
    increase performance. Disabling the Twig cache will recompile the templates
    from source each time they are used. In most cases the twig_auto_reload
    setting above should be enabled rather than disabling the Twig cache.
  • Not recommended in production environments (Default: true).

Drupal render cache

By default, Drupal caches any rendering it performs for blocks and entities, to speed up subsequent page loads. This means that changes to Twig templates for these will not take effect immediately. Setting the render cache to use the Null cache back-end effectively disables this.

To disable the render cache, uncomment the following lines from the bottom of settings.php and then save the file.

<?php if (file_exists(__DIR__ . '/settings.local.php')) {   include __DIR__ . '/settings.local.php'; } ?>

Clear the cache

Go to Configuration -> Performance and then click the Clear all caches button.

Next copy sites/example.settings.local.php to sites/default/settings.local.php.

In settings.local.php uncomment the following lines and then save the file:


$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';

Refresh the page you are inspecting to see the Twig debugging information in the page source.

For more information about the implementation of the Twig environment settings in Drupal, visit #1843034: Make Twig settings configurable

Drupal Render Cache is not been supported by Drupal Console for more information about the status of this implementation please visit -

Sample blackbox block

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas non porta odio, id mattis erat.

Nam sed tincidunt eros. Donec a venenatis odio, vitae commodo sem. Vivamus ullamcorper pellentesque erat, in adipiscing tortor scelerisque sit amet. Nulla pulvinar urna magna. Vivamus a ipsum lorem. Etiam adipiscing pulvinar lorem.