The Edit-and-See-It Loop
Which command makes each kind of edit take effect, and why the config cache makes working code look broken.
bin/magento cache:clean [type] ... [type] | bin/magento cache:flushMagento reads its configuration once, merges it across every enabled module, and caches the result. An edit on disk is therefore not live until you tell Magento to forget what it cached. The loop is: change a file, run one command, reload.
Change to command
| What changed | What to run |
|---|---|
Any module XML, such as di.xml or config.xml | bin/magento cache:clean config |
| A template or a layout file | bin/magento cache:clean layout block_html full_page |
| A new module, a schema file, or a data patch | bin/magento setup:upgrade |
| A changed constructor signature | nothing in developer mode; otherwise clear generated/ |
| LESS or other static assets | delete the theme's directory under pub/static and var/view_preprocessed |
Clean or flush
cache:clean removes entries for enabled cache types only. cache:flush purges the whole cache storage, including anything else sharing that Valkey or Redis instance. Flush when you are unsure; clean when the storage is shared.
The cache that is lying to you
Two of them. The config cache holds the merged XML, so a new di.xml entry does nothing until it is cleaned. The full_page cache answers a logged-out GET from a stored copy of the HTML, so your template edit is real but unseen. When a change seems to have had no effect, clean config, then disable full_page, and only then start doubting the code.
Shorthand
The CLI is Symfony Console, so any unambiguous abbreviation works: c:f is cache:flush, s:up is setup:upgrade. An ambiguous abbreviation errors instead of guessing.
Example
# from the Magento root, in developer mode
# 1. module XML changed - the merged configuration is cached
bin/magento cache:clean config
# 2. a template or layout file changed and the page is cached
bin/magento cache:clean layout block_html full_page
# 3. a new module, a schema file, or a data patch
bin/magento setup:db:status
bin/magento setup:upgrade
# 4. generated code looks stale
rm -rf generated/code generated/metadata
# the same two commands in Symfony's abbreviated form - identical to the long form
bin/magento c:f
bin/magento s:up
# Terminal output:
# Cleaned cache types:
# config
# Cleaned cache types:
# layout
# block_html
# full_page
# All modules are up to date.
# Nothing to import.When to use it
- Decide, after editing a file, whether you owe a cache clean, a setup:upgrade, or nothing.
- Work out why a colleague's module appears to be installed but its configuration is ignored.
- Write a short script that your team runs after every git pull.
- Stop losing an afternoon to a template change that the full page cache was hiding.
More examples
Checking whether setup:upgrade is owed
setup:db:status takes no arguments and answers one question, which makes it the right thing to put in a deploy script or a git hook. The --keep-generated option stops setup:upgrade from clearing compiled code and static content, which matters when those were built in a separate build stage rather than on the server.
bin/magento setup:db:status
# exit code 0: nothing to do
# exit code 1: no answer - the application is not installed
# exit code 2: setup:upgrade is required
bin/magento setup:upgrade
# on a production deploy, keep the files a build step already produced
bin/magento setup:upgrade --keep-generatedForcing static files to rebuild
Use this when a LESS or JavaScript change refuses to appear. The symlinks in pub/static point at whatever existed when the page was first rendered, so deleting the theme directory is what makes Magento build them again. Deploying explicitly with --force is the faster route when you are changing many files at once.
# in developer mode, files under pub/static are symlinks created on demand
rm -rf pub/static/frontend/* var/view_preprocessed/*
bin/magento cache:clean
# or deploy them explicitly; -f and --force are the same option and are what
# allow the command to run outside production mode
bin/magento setup:static-content:deploy -f en_US
bin/magento setup:static-content:deploy --force en_USTurning off the caches that hide your work
Disabling these three while working on the storefront removes the main source of "my change did nothing". Turn them back on before you measure anything, because a site with full_page disabled is several times slower and will mislead you about performance. cache:status prints the current state of every type, which is worth checking before you trust a timing.
bin/magento cache:disable full_page block_html layout
# ... work on templates ...
bin/magento cache:enable full_page block_html layout
bin/magento cache:flush
bin/magento cache:status
Discussion