Upgrade to the official Akismet Drupal module

If your Drupal site still runs the community Akismet module (drupal/akismet), the official Akismet module (drupal/akismet_antispam) can upgrade it in place. You swap the Composer package, run database updates, and your API key and protection settings come along. We built it so you don’t have to uninstall, reinstall, and re-enter everything. This post walks through the steps.

Which sites this covers

The update needs Drupal 10.3 or later on PHP 8.1 or later. That covers sites on the community module’s 2.0.x releases and its 8.x-1.x dev branch.

If you’re on an older setup:

8.x-1.0-alpha2 (Drupal 8 or 9): update the community module to 2.0.0-alpha2 while you update core, then follow this post.
7.x: upgrade Drupal first, then install the official module fresh. Your Akismet account and API key still work.

The migration guide on drupal.org has a table for every release if you’re not sure which one you run.

Before you start

Back up the database. The update only goes one way.
Note which roles have “Bypass Akismet protection.” The update removes that permission (more on that below).
Plan one deploy for the whole swap. Between the Composer change and drush updb, spam protection is off and some admin pages break, so don’t leave a gap between them.

What carries over, and what doesn’t

These come along:

Your API key
Your connection timeout, if it’s between 1 and 60 seconds
Your comment, contact and registration protection settings

These don’t:

Check history. The community module’s akismet table is dropped, so the Spam tab starts empty. Those rows hold submitted content, including author emails and IP addresses, and the official module has no way to erase them later.
Per-form settings. The community module could protect some comment types or contact forms and not others. The official module has one toggle per category, and it covers all of them.
Per-form “discard spam.” This becomes one site-wide strictness setting.
Test mode, custom API endpoints and the “block all submissions” outage policy.
The “Bypass Akismet protection” permission. The update removes it from every role that had it. The official module’s equivalent is bypass akismet, and it isn’t granted automatically.
Webform handlers. You’ll need to re-attach the Akismet handler to each webform that used it.

You don’t have to track any of this by hand. The update prints a report that names every item above that applies to your site.

The migration

			
composer remove drupal/akismet
composer require drupal/akismet_antispam -W
drush cr
drush updb

Run them in that order, back to back.

composer remove first, and leave the module installed in Drupal. Don’t uninstall it, because the update reads its database state. The official module’s composer.json conflicts with drupal/akismet, so Composer won’t install them side by side.
composer require ... -W lets Composer update shared dependencies, like the Akismet PHP SDK or the PSR HTTP packages, if your lock file pins an older version. Without -W, Composer can refuse with “the package is fixed to … (lock file version).”
drush cr before anything else. The community module shipped services that no longer exist, and Drupal still has them cached. Until you rebuild, logged-in pages return a 500 and drush commands die on shutdown. drush cr works when nothing else does.
drush updb runs the update. Stay off the comment admin screens until it finishes.

Read the report. It’s also logged to watchdog, so you won’t lose it if your terminal scrolls away. Then export and commit the new configuration:

drush cex

On every other environment, rebuild the cache before anything else touches it:

drush cr && drush deploy

Check that it worked

Settings: confirm your protection toggles at /admin/config/content/akismet.
Status report: check the Akismet entries at /admin/reports/status.
Test submission: post a comment as an anonymous user named akismet-guaranteed-spam. Akismet always flags that name, so the comment should land in the Spam tab.

Already on the official module 1.0?

Upgrading to 1.1 is one command and a database update:

			
composer update drupal/akismet_antispam -W
drush updb

The -W matters here. Version 1.1 needs Akismet PHP SDK 1.5, and if your lock file still pins 1.4, Composer stops with:

			
drupal/akismet_antispam 1.1.0 requires automattic/akismet-sdk ^1.5 -> found automattic/akismet-sdk[v1.5.0] but the package is fixed to v1.4.0 (lock file version).

-W (short for --with-dependencies) lets Composer update the SDK along with the module.

Questions

If something in the report surprises you, or the update doesn’t go the way this post says, open an issue in the issue queue. The migration guide and the module’s README have the full details.