Skip to content
zefıly
← All posts

How to update Statamic safely (and how to go back)

5 min read

The order that keeps a Statamic update boring. Check the version, back up the right folders, update with Composer on a copy first, clear the right caches, and roll back in one step if something breaks. Tested with Statamic 6.

Updating Statamic is one Composer command. What decides whether the update is boring or a bad afternoon is everything around that command: where you run it, what you saved before, and what you clear after.

We tested the commands here on 12 November 2026 with a new Statamic 6.41.0 project (Laravel 13, PHP 8.5).

In short

  • The update command is composer update statamic/cms --with-dependencies.
  • Never run it first on the live site. Run it on a copy, test, then deploy the result.
  • Before updating, save composer.lock and the folders that hold your content: content/, users/, resources/ and your assets.
  • After updating, run php please stache:warm and clear the static cache if you use it.
  • To go back, restore composer.json and composer.lock and run composer install.

1. Know what you have

php please --version

and the fuller picture:

php please support:details
Laravel Version: 13.42.0
PHP Version: 8.5.12
...
Statamic

Then look at composer.json:

"statamic/cms": "^6.0"

The ^6.0 means: any 6.x release, never 7. This decides which kind of update you are about to do.

2. Minor update or major upgrade?

Within the same major version (6.38 to 6.41): small, frequent, and meant to be safe. Statamic releases these often; 6.41.0 came out on 11 November 2026. This is the update you should do regularly, because security fixes arrive this way.

To a new major version (5 to 6): a project, not an update. The requirement changes too: the newest Statamic 5 release needs Laravel 12, and Statamic 6 needs Laravel 12.40 or 13. Read the official upgrade guide for that version from start to finish, change the constraint in composer.json:

"statamic/cms": "^6.0"

and expect to fix things. Go one major version at a time.

3. Back up the right things

Statamic keeps content in files, not in a database. That makes backup simple, but only if you take the right folders:

What Where
Entries, taxonomies, globals, navigation content/
Users users/
Blueprints, fieldsets, forms, templates resources/
Uploaded assets usually public/assets/ (check your asset containers)
Form submissions storage/forms/
The exact package versions composer.json and composer.lock
Secrets and settings .env

If the project is in Git, most of this is already saved: commit before you update. Assets, form submissions and .env are usually not in Git; copy them.

If you moved content to a database with the Eloquent driver, dump the database too.

4. Update on a copy first

On your own machine or a staging copy of the site:

composer update statamic/cms --with-dependencies

--with-dependencies lets Composer also update the packages Statamic needs. Without it, the update often stops with a conflict.

To update addons and everything else at the same time, run composer update without a package name. Do this as a separate step. If something breaks after you changed thirty packages at once, you do not know which one did it.

Statamic runs its own update scripts after the Composer update. If you ever need to run them again by hand:

php please updates:run 6.38

with the version you came from.

5. Clear what is cached

php artisan optimize:clear
php please stache:warm

The Stache is Statamic's index of your content files. After an update, rebuild it once so that the first visitor does not pay for it.

If you use static caching:

php please static:clear
php please static:warm

Old cached pages were made by the old version. Do not keep them.

6. Test like a visitor and like an editor

  • Open the home page, a collection page, an entry, a taxonomy page.
  • Submit a form.
  • Search, if the site has search.
  • Log in to the control panel at /cp. Open an entry, change it, save it. Upload an asset.
  • Read storage/logs/laravel.log.

Most update problems show up in the control panel, not on the front end: a custom fieldtype or an addon that does not support the new version yet. Check each addon's supported versions before a major upgrade.

7. Deploy the result, do not repeat the update

On the live server, do not run composer update. Bring over the composer.lock you just tested and run:

composer install --no-dev --optimize-autoloader
php artisan optimize
php please stache:warm

composer install installs exactly the versions in the lock file: the ones you tested. composer update on the server would pick whatever is newest at that moment, which may be a release you have never seen.

8. If it goes wrong

Because the lock file names every version, going back is short:

git checkout HEAD~1 -- composer.json composer.lock
composer install --no-dev --optimize-autoloader
php artisan optimize:clear
php please stache:warm

Without Git, put back the two files you saved in step 3 and run the same commands.

If the update also changed content files (some major upgrades do), restore content/ and resources/ from your backup as well.

How often?

Minor updates: every few weeks, and immediately when a release mentions a security fix. Waiting a year turns twelve small updates into one large, risky one.

With Zefily

Zefily installs Statamic as a one-click app on your own server: Composer project, PHP version, HTTPS and the super user account are set up for you. For updates, the two things this guide asks for are built in: a staging copy of the site to run the update on, and backups you can restore. See PHP apps and Backups.

For the server side, see Hosting Statamic on your own server.

Frequently asked questions

What is the command to update Statamic?

composer update statamic/cms --with-dependencies. Run it on a local or staging copy, test, then deploy the composer.lock file and run composer install on the server.

Do I need to back up a database before updating Statamic?

Usually not, because Statamic stores content in files. Back up content/, users/, resources/, your assets, storage/forms/ and composer.lock. Dump the database only if you use the Eloquent driver.

How do I roll back a Statamic update?

Restore the previous composer.json and composer.lock, run composer install, then clear the caches and run php please stache:warm.

Should I run composer update on the production server?

No. Run composer install there, so the server gets exactly the versions in the lock file that you tested.

What should I run after updating Statamic?

php artisan optimize:clear and php please stache:warm, plus php please static:clear and static:warm if you use static caching.

See PHP apps for the apps Zefily installs.

More posts

Black Friday & Cyber Monday

Before you go: lifetime plans are on sale

Pay once for a lifetime plan, or get 30% off the first year of any yearly plan.

Only 100 lifetime plans per plan. When they are gone, they are gone.

See the campaign

Amazing November

See the campaign →