Automatic Updates and Project Browser

This content was generated with the assistance of AI and should be verified against the official Drupal documentation before being relied on in production.

This sub-section’s Drupal bibliography lists the reference material consulted while preparing these pages.

Since Drupal 11.2 the supported way to add or update code is Composer, and the administration interface cannot download or upgrade extensions any more. Two contributed modules bring a graphical workflow back on top of Composer: Automatic Updates applies patch-level core updates, and Project Browser finds modules and recipes and installs them with a click. Both are built on a hidden core module, Package Manager, which copies the site into a sandbox, runs Composer there and then copies the result back. This page explains how the three pieces fit together, what each one requires, how to configure and secure them, and why the Meridian Museum site (the running example of this sub-section) should use them only where the hosting allows it.

The page was written against Drupal 11.4.x, Automatic Updates 4.1.x, Project Browser 2.1.x, Composer 2.6 or later and PHP 8.3 or later, and checked on 2026-10-30. Drupal 12.0.0 is scheduled for the week of 2026-12-07 and Drupal 10 reaches its end of life on 2026-12-09. The Composer workflow the modules wrap is described in Installation with Composer and DDEV, the routine update procedure and security advisories in "Updates, Composer and Security Advisories", and the lifecycle of releases in "Versions, Release Cycle and Support".

The three pieces

Piece What it is Status on 2026-10-30

Package Manager (package_manager)

A core module with no user interface. It exposes an API to create a sandbox copy of the project, run composer require or composer update in it, validate the result and apply it to the live codebase. It declares itself hidden and experimental in its package_manager.info.yml and depends on the Update module.

Added as a hidden experimental module in 11.1. Considered API-stable from 11.2, so contributed modules can rely on its APIs, but it remains hidden and experimental as a module.

Automatic Updates (automatic_updates)

A contributed module that adds the Update pages under Reports and applies patch-level Drupal core updates through Package Manager. It adds an administer software updates permission and readiness checks on the status report.

4.1.0 was released on 2026-01-20 and works with Drupal ^11.2. 4.0.0 (2025-06-11) was the first release to rely on the core Package Manager. The 3.x line (for Drupal 10.1 and 11) carried its own copy of Package Manager.

Project Browser (project_browser)

A contributed module that adds a Browse tab under Extend, queries Drupal.org (and the recipes already in the codebase) and can install the chosen project.

2.1.5 (2026-09-23) works with Drupal ^11.2 or ^12. The 2.0.x line (2.0.3) works with Drupal 10.4, 11.0 and 11.1.

Older books such as Drupal 10 Masterclass (2023) describe Automatic Updates and Project Browser as future initiatives, and Drupal 10 Development Cookbook (2023) does not cover them at all. Both modules exist today, Package Manager is in core since 11.1 and the 11.2 release notes require Automatic Updates 4.0.0 or later and Project Browser 2.1.0-beta2 or later to be installed at the same time as Drupal 11.2.

What changed in Drupal core

Drupal 11.2 removed the ability to download or update extensions from the administration interface. The release notes state that sites can no longer download or update extensions from the user interface and advise Composer instead; the notification of available updates remains on the Available updates report (/admin/reports/updates). Uploading a module or theme archive from the UI had already been removed in 10.4/11.0. The practical consequence is that a tutorial that says "go to Extend, Install new module, paste the URL" no longer applies to any supported release. The two modules in this page are the sanctioned way to get a graphical workflow back, and both still need a Composer-managed site.

Source: Drupal 11.2.0 release notes

Package Manager internals

Package Manager is built on the php-tuf/composer-stager library. The core idea is a stage (named sandbox from 11.4): a full copy of the project root, with a few paths excluded, in which Composer can run without touching the live site. If anything fails, the sandbox is thrown away and the live site is unchanged.

sequenceDiagram participant A as Administrator participant M as Manager (automatic_updates or project_browser) participant P as Package Manager participant S as Sandbox copy participant L as Live codebase A->>M: start update or install M->>P: create() P->>S: copy project root (minus excluded paths) M->>P: require(runtime, dev) P->>S: composer require / update P->>P: validators on pre and post events A->>M: confirm on "Ready to update" M->>P: apply() P->>L: sync changed files M->>P: postApply() and destroy() P->>L: run database updates, clear caches

Lifecycle and events

A consumer subclasses the base class (StageBase in 11.2 and 11.3, renamed SandboxManagerBase in 11.4, with the event classes following suit) and calls the following methods in order:

  • create() makes the sandbox. It marks the stage as unavailable first, so two administrators cannot create stages at once, and returns a random 32-character stage ID.

  • require($runtime, $dev) runs Composer in the sandbox for the given packages.

  • apply() copies the changes back to the live project; postApply() and destroy() clean up.

  • claim($unique_id) lets a later request (the confirmation form) take over a stage created by an earlier one. The lock and metadata live in a shared temporary store named package_manager_stage, so the stage is tied to the user’s session.

Each step dispatches a pre- and a post-event (PreCreateEvent, PostCreateEvent, PreRequireEvent, PostRequireEvent, PreApplyEvent, PostApplyEvent). Validators are ordinary event subscribers that call addError() on the event, and an error aborts the operation. Core ships about twenty of them: the Composer executable and version, disk space, writable file system, minimum stability, multisite, symlinks, duplicate info files, pending database updates, a lock file that changed behind the stage’s back, trusted Composer plugins, Composer patches, supported releases and others. The names of the event and base classes changed between 11.2 and 11.4, so a custom subscriber should be checked against api.drupal.org for the exact core version in use.

Settings

Package Manager has a small configuration object, package_manager.settings:

# config/sync/package_manager.settings.yml
additional_trusted_composer_plugins: []
include_unknown_files_in_project_root: false
# log: /var/log/drupal/package_manager.log   # optional: Composer Stager process output

additional_trusted_composer_plugins lists Composer plugins that are allowed to run in the sandbox. A plugin that is not trusted makes the validator fail, so a site that uses an uncommon scaffolding plugin adds it here. include_unknown_files_in_project_root controls whether files in the project root that Package Manager does not recognise (a stray Makefile or .env) are copied into the sandbox; by default they are not, which also means they are not synced back. The path of the Composer binary (and of rsync, which speeds up copying) is detected automatically or configured as described in the module’s help page at admin/help/package_manager for the installed version. Composer must be at least version 2.6 for Automatic Updates, and PHP must be allowed to execute it.

Source: Automatic Updates project page

Automatic Updates 4.x

Installing and enabling

Install with Composer, then enable the module like any other:

cd /var/www/meridian
composer require 'drupal/automatic_updates:^4.1'
drush pm:install automatic_updates
drush cache:rebuild

Source: Automatic Updates project page

Installing the module also enables Package Manager and Update. Use 4.1.x or later on Drupal 11.2 and later; the 3.x line is for Drupal 10.1 and is kept for older sites. The project page lists the Composer 2.6 minimum and the following limits, which are the ones to check before relying on it:

  • the site must be managed by Composer, and the web server user must be able to modify its own codebase; the project page warns that the module is likely incompatible with most Acquia and Pantheon offerings

  • it applies patch-level core updates (for example 11.4.3 to 11.4.4); updating across a minor version (11.3 to 11.4) is experimental, disabled by default and can only be enabled with the allow_core_minor_updates setting, not from the UI, and updates across major versions are not supported

  • multisite installations are not supported

  • a completed update cannot be undone, and a development snapshot of core cannot be updated to another version

  • the page says that fully unattended updates during cron runs are not yet possible, and that updating contributed modules and themes is experimental and not recommended for production

The 4.x configuration schema contains an unattended mapping with a method (console or web) and a level (disable, security or patch), whose default is disable, plus cron_port and status_check_mail. The project page and the schema describe the unattended capability differently, so the supported position is: leave level at disable on a production site and treat unattended updates as unsupported until the project page says otherwise. Version 4.1.0 is described as merging the formerly separate Automatic Updates Extensions sub-module, which handles contributed projects, into the main module.

The configuration object

# config/sync/automatic_updates.settings.yml
unattended:
  method: web
  level: disable
allow_core_minor_updates: false
status_check_mail: errors_only

Source: Automatic Updates project page

status_check_mail controls whether the readiness checks that cron runs periodically send an email when they fail. The configuration form is linked from the module list and sits with the other update settings at /admin/reports/updates/settings.

The update workflow

  1. A security or bugfix release appears on the Available updates report, because Drupal.org publishes release data that the Update module reads on cron.

  2. Open Reports > Available updates > Update (/admin/reports/updates/update). The page runs the readiness checks, shows the target version and offers an Update button. The route requires the administer software updates permission, which should be given only to site administrators because it lets a user run Composer on the server.

  3. The sandbox is created and composer update runs there while visitors keep using the live site; only the final copy to the live codebase is a risky step, which is why the site should be backed up first.

  4. The confirmation page /admin/automatic-update-ready/{stage_id} lists the Composer packages that will change. After the administrator confirms, apply() copies the files, the module runs database updates and clears caches, and /automatic-update/finish reports the result.

The readiness checks are the same validators that run during the update. They also appear on the status report (/admin/reports/status) and under Reports > Update readiness (/admin/automatic_updates/status), so problems such as a read-only file system, low disk space or a missing Composer binary are found before the day an urgent security release arrives. An administrator who relies on the module should schedule a periodic look at that page, or enable the email notification above.

The command-line entry point

The module ships a console script, auto-update, in its bin directory, which Composer links into vendor/bin. It is meant for hosts where the web server user cannot write to the codebase: cron runs it as a more privileged user, so the PHP process serving visitors never needs write access. Whether to use it depends on the hosting; see the requirements and hosting page.

Project Browser 2.x

What it does

Project Browser adds Extend > Browse (/admin/modules/browse). It queries the Drupal.org API in real time and shows only projects compatible with the site’s core version, with filtering by category, maintenance and security status, and so on. A project is shown with its Composer command, so even when automatic installation is not allowed the developer gets the command to paste. Its project page says the module is aimed at site builders new to Drupal and is intended for local development environments such as DDEV.

composer require 'drupal/project_browser:^2.1'
drush pm:install project_browser

Source: Project Browser project page

Use the 2.1.x line on Drupal 11.2 or later (and Drupal 12) and the 2.0.x line on Drupal 10.4, 11.0 and 11.1. The module’s info.yml requires core ^11.2 or ^12 for 2.1.x, and it needs no other module. The sources are:

  • the Drupal.org source (plugin drupalorg_jsonapi), enabled by default and the default source

  • the Recipes source, which lists the recipes already present in the codebase (for example under recipes/)

  • the Core source (drupal_core), which lists core modules and is off by default

Configuration and permissions

# config/sync/project_browser.admin_settings.yml
enabled_sources:
  drupalorg_jsonapi: {}
  recipes: {}
allow_ui_install: false
default_source: drupalorg_jsonapi

Source: Project Browser project page

allow_ui_install is the switch that matters. Its default is false: the module then only shows projects and their Composer commands. Setting it to true (on Configuration > Development > Project Browser, /admin/config/development/project_browser) lets the Install button run Composer through Package Manager and activate the project. The browse and activate routes require the administer modules permission and the activate and uninstall routes also demand a CSRF token. The web user needs write access to the codebase for UI installation to work, which is the same condition as for Automatic Updates.

A worked example for the Meridian Museum

On a local DDEV copy of the site, a site builder enables UI installation to try a search module and the meridian_events recipe; on the production host the setting stays false.

ddev drush config:set project_browser.admin_settings allow_ui_install true -y
ddev drush config:export -y
git diff config/sync/project_browser.admin_settings.yml

Source: Project Browser project page

The exported file then contains allow_ui_install: true. It must not be deployed: configuration split (see Configuration Management) should keep it in a local-only split, so a production import cannot switch it on. Recipes shown in the browser are applied with drush recipe or php core/scripts/drupal recipe; see Recipes for how they work and why a recipe has no update path after it has been applied.

Security and production caveats

  • The web user can change the code. Both modules need the PHP process that serves visitors to be able to write to the project root and to run Composer. A single remote-code-execution flaw then becomes a way to alter any file. This is the main reason these modules are recommended for development and for hosts where the trade-off was made deliberately.

  • Composer packages are code. Installing a module from the UI is composer require of third-party PHP that runs with the privileges of the site. Package Manager can verify packages through TUF (The Update Framework) metadata for packages.drupal.org, but only for the Drupal.org repository; patches and other repositories are not covered.

  • Permissions. Grant administer software updates and administer modules only to administrators and require two-factor authentication for them (see Security Hardening).

  • No rollback. A completed update cannot be undone from the UI, so take a database and files backup first (see Backups and Disaster Recovery).

  • Contributed project updates are not production-ready. Update modules and themes by Composer in a pipeline and review composer.lock in Git (see Deployment and CI/CD).

  • Immutable hosts. A container or a managed platform with a read-only file system cannot use either module. The usual pattern there is to build a new image or deployment per update (see Docker and Containers).

For the Meridian Museum the recommended arrangement is: Project Browser and allow_ui_install only on developers' DDEV copies; Automatic Updates optional on a single-server staging host to try patch releases, and never unattended.level set to anything but disable in production; and the production site updated by the same Composer pipeline that deploys everything else.

Common errors and pitfalls

  • "Composer was not found" or version too old. The readiness checks fail when the Composer binary cannot be found by the PHP process (its PATH differs from the shell’s) or is older than 2.6. Fix the path as described in the help page, or upgrade Composer.

  • "The file system is not writable." Owners and modes after a composer install run as another user. The sandbox and the live project root must be writable by the same user as PHP.

  • Cannot create a stage because one already exists. A previous attempt crashed. Wait for the lock to expire or destroy the stage from the update page; in the worst case a failure marker file remains and must be cleared before a new stage can be created.

  • Multisite error. The multisite validator fails when more than one site directory exists. Update by Composer.

  • Symlinks, duplicate .info.yml files or composer patches. Symlinks pointing outside the project, copies of a module in two places and patches applied by cweagans/composer-patches each have a validator that blocks the update until fixed.

  • Pending database updates. The sandbox refuses to start while a core or module database update is pending; run drush updatedb first.

  • Update succeeds but the site is broken. The module stops at the Composer level and does not run the test suite. Test the same update on a copy first.

  • Reading old tutorials. Guides that tell the reader to "upload a module" or press Update in the Available updates report to download code describe Drupal 8 to 10 behaviour and no longer work.

Version notes and corrections of older material

  • Package Manager was added to core in 11.1 as a hidden experimental module and declared API-stable in 11.2; the experimental modules list may still show an older lifecycle label for it.

  • Drupal 11.2 removed UI-based code downloads and updates. Automatic Updates must be 4.0.0 or later and Project Browser 2.1.0-beta2 or later on Drupal 11.2 and later.

  • Automatic Updates 3.x (Drupal 10.1 and 11) bundled its own Package Manager; when both exist, the module’s copy wins during module discovery, which is why upgrading to 4.x at the same time as 11.2 matters.

  • Project Browser 2.1.x supports Drupal 12; 2.0.x does not.

  • Drupal 10 reaches end of life on 2026-12-09, after which neither module line receives a supported core. Drupal 10 Masterclass and Drupal 10 Development Cookbook (both 2023) predate this and should be read for concepts only.

References