The Services API is how you declare and use services. The container is the runtime object that holds those definitions and builds the objects. Dependency injection is the habit of receiving what you need. The three terms describe one system from different sides.
' - '@type': Question name: 'Can I change a service for one site without writing a module?' acceptedAnswer: '@type': Answer text: 'Yes. A file named services.yml in the site directory can register site-specific service definitions or change container parameters. The settings template default.settings.php adds it to the container_yamls setting, and core ships default.services.yml as the template to copy.
' - '@type': Question name: 'What is a lazy service?' acceptedAnswer: '@type': Answer text: 'A service declared lazy is replaced by a proxy in the classes that inject it. The real service is created only when a method is called. This helps when a service is expensive to build but rarely used.
' - '@type': Question name: 'How do I rebuild the container?' acceptedAnswer: '@type': Answer text: 'Clear all caches. With Drush, run drush cache:rebuild or drush cr. A full cache rebuild invalidates the cached container and builds a new one.
' - '@type': TechArticle headline: 'Service container' description: 'The object Drupal code gets its services from, such as the database or mailer, built by the kernel from core and module services.yml files.' image: '@type': ImageObject url: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg' width: '1200' height: '630' datePublished: '2026-10-26T18:01:04+0000' dateModified: '2026-10-26T18:01:04+0000' author: '@type': Organization '@id': 'https://dxpr.com/#organization' name: DXPR url: 'https://dxpr.com/' logo: '@type': ImageObject url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg' width: '1348' height: '501' publisher: '@type': Organization '@id': 'https://dxpr.com/#organization' name: DXPR url: 'https://dxpr.com/' logo: '@type': ImageObject url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg' width: '1348' height: '501' mainEntityOfPage: 'https://dxpr.com/hc/documentation/learn-drupal/drupal-glossary/service-container' articleSection: 'Drupal glossary' - '@type': WebPage '@id': 'https://dxpr.com/hc/documentation/learn-drupal/drupal-glossary/service-container' description: 'The object Drupal code gets its services from, such as the database or mailer, built by the kernel from core and module services.yml files.' breadcrumb: '@type': BreadcrumbList itemListElement: - '@type': ListItem position: 1 name: Home item: 'https://dxpr.com/' publisher: '@type': Organization '@id': 'https://dxpr.com/#organization' name: DXPR inLanguage: en --- [Help Center](/hc)/[Documentation](/hc/documentation) /[Learn Drupal](/hc/documentation/learn-drupal) /[Drupal glossary](/hc/documentation/learn-drupal/drupal-glossary) # Service container The object Drupal code gets its services from, such as the database or mailer, built by the kernel from core and module services.yml files. Learn DrupalDrupal glossary Last updated October 26, 2026 ## In this guide Related terms - [Services API](/hc/documentation/learn-drupal/drupal-glossary/services-api) - [Dependency injection](/hc/documentation/learn-drupal/drupal-glossary/dependency-injection) - [Hook system](/hc/documentation/learn-drupal/drupal-glossary/hook-system) - [Cache](/hc/documentation/learn-drupal/drupal-glossary/cache) - [Drush](/hc/documentation/learn-drupal/drupal-glossary/drush) - [Module](/hc/documentation/learn-drupal/drupal-glossary/module) [All Drupal terms from A to Z](/hc/documentation/learn-drupal/drupal-glossary) The service container is the object that knows every service on a Drupal site and builds each one when code asks for it. Drupal collects the service definitions from modules and settings, compiles them once into a single definition, caches that result, and hands out one shared instance per service unless a definition says otherwise. The container is what turns a line in a services file into a working object. ## How the container is built in Drupal 11 The Drupal kernel, `DrupalKernel`, builds the container in stages. This describes the 11.4.10 code. 1. **Discovery.** The kernel adds `core/core.services.yml` and the `CoreServiceProvider` class. For each enabled module it adds `MODULE.services.yml` and, if one exists, a class named after the module, such as `MyModuleServiceProvider`. Site files listed in `$settings['container_yamls']` come last. 2. **Registration.** The YAML is loaded and each provider's `register()` method runs. Site-level files and providers load after the app ones, so they can override. 3. **Compilation.** Compiler passes process the definitions. Tags such as `event_subscriber` and `cache.bin` are collected here, because a tag does nothing on its own until a pass acts on it. A provider that implements `ServiceModifierInterface` can change definitions in `alter()`. 4. **Caching.** The kernel dumps the result to an array and stores it in the `container` cache bin. The cache key includes a hash of the installed Composer package versions (or the Drupal version when the Composer scaffold has not generated that hash), the `deployment_identifier` setting, the operating system and the `container_yamls` list. On later requests the kernel loads the cached definition instead of compiling. A service is created the first time something requests it, and it is shared by default, so every consumer gets the same object. The `drupal_flush_all_caches()` function invalidates the cached container and rebuilds it, which is what a full cache rebuild does. One newer detail matters to developers. In 11.4.10 the `HookCollectorPass` compiler pass finds classes in a module's `Hook` namespace whose class or methods carry the `#[Hook]` attribute and registers them as autowired services. The class marks itself internal. Because that registration happens while the container is compiled, a new hook class is not picked up until the container is rebuilt; see [hook system](/hc/documentation/learn-drupal/drupal-glossary/hook-system). ## Example Core ships `default.services.yml` as a template. Copy it to `sites/default/services.yml`, and the container picks it up through `container_yamls`. The template contains the container parameter `security.enable_super_user`. Its comment advises setting it to `false` when the site has at least one user with the Administrator role, so that user 1 can be made a regular user. ```yaml parameters: security.enable_super_user: false ``` Save the file and run `drush cr`. The next request compiles a container with the new parameter value. ## Common mistakes - **Overriding part of an array parameter.** Core merges service files shallowly. To change one value inside a parameter such as `twig.config`, copy the whole parameter from the default file, as the comment in `development.services.yml` says. - **Serializing the container.** The core container class triggers an assertion if it is serialized. Classes that must survive serialization use `DependencySerializationTrait` and store service IDs, not the container. - **Leaving development parameters on.** The default services file marks Twig debugging as not recommended for production. ## For marketing and content teams You never touch the container, but you may hear that a change "needs a cache rebuild". This is why: Drupal builds the container once and reuses it, so developer changes to services, hooks and some settings appear only after the rebuild. Ask for the rebuild to be part of every deploy. The first request after a rebuild compiles the container again. For the building blocks, read [Services API](/hc/documentation/learn-drupal/drupal-glossary/services-api) and [dependency injection](/hc/documentation/learn-drupal/drupal-glossary/dependency-injection). ## Sources - [Services and Dependency Injection Container topic, core.api.php, Drupal 11.4.10](https://git.drupalcode.org/project/drupal/-/raw/11.4.10/core/core.api.php) - [DrupalKernel, Drupal 11.4.10 source](https://git.drupalcode.org/project/drupal/-/raw/11.4.10/core/lib/Drupal/Core/DrupalKernel.php) - [CoreServiceProvider, Drupal 11.4.10 source](https://git.drupalcode.org/project/drupal/-/raw/11.4.10/core/lib/Drupal/Core/CoreServiceProvider.php) - [HookCollectorPass, Drupal 11.4.10 source](https://git.drupalcode.org/project/drupal/-/raw/11.4.10/core/lib/Drupal/Core/Hook/HookCollectorPass.php) - [Core Container class, Drupal 11.4.10 source](https://git.drupalcode.org/project/drupal/-/raw/11.4.10/core/lib/Drupal/Core/DependencyInjection/Container.php) - [Component Container, Drupal 11.4.10 source](https://git.drupalcode.org/project/drupal/-/raw/11.4.10/core/lib/Drupal/Component/DependencyInjection/Container.php) - [default.services.yml, Drupal 11.4.10 source](https://git.drupalcode.org/project/drupal/-/raw/11.4.10/core/assets/scaffold/files/default.services.yml) - [Drush cache:rebuild command](https://www.drush.org/13.x/commands/cache_rebuild/) ## Questions about Service container ### How is the service container different from the Services API? The Services API is how you declare and use services. The container is the runtime object that holds those definitions and builds the objects. Dependency injection is the habit of receiving what you need. The three terms describe one system from different sides. ### Can I change a service for one site without writing a module? Yes. A file named services.yml in the site directory can register site-specific service definitions or change container parameters. The settings template default.settings.php adds it to the container\_yamls setting, and core ships default.services.yml as the template to copy. ### What is a lazy service? A service declared lazy is replaced by a proxy in the classes that inject it. The real service is created only when a method is called. This helps when a service is expensive to build but rarely used. ### How do I rebuild the container? Clear all caches. With Drush, run drush cache:rebuild or drush cr. A full cache rebuild invalidates the cached container and builds a new one. ## Cite this definition "Service container." DXPR Drupal glossary, https://dxpr.com/hc/documentation/learn-drupal/drupal-glossary/service-container. Last updated October 26, 2026. Copy ## Related terms - [Services API](/hc/documentation/learn-drupal/drupal-glossary/services-api) - [Dependency injection](/hc/documentation/learn-drupal/drupal-glossary/dependency-injection) - [Hook system](/hc/documentation/learn-drupal/drupal-glossary/hook-system) - [Cache](/hc/documentation/learn-drupal/drupal-glossary/cache) - [Drush](/hc/documentation/learn-drupal/drupal-glossary/drush) - [Module](/hc/documentation/learn-drupal/drupal-glossary/module) [All Drupal terms from A to Z](/hc/documentation/learn-drupal/drupal-glossary)