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.lockand the folders that hold your content:content/,users/,resources/and your assets. - After updating, run
php please stache:warmand clear the static cache if you use it. - To go back, restore
composer.jsonandcomposer.lockand runcomposer 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.