Magento 2: cache:clean, cache:flush, and setup:upgrade – Understanding and Optimizing Their Usage

Differences Between cache:clean and cache:flush

The question comes up often: what’s the difference between cache:clean and cache:flush in Magento 2?

• cache:clean only removes obsolete or invalid Magento cache entries, leaving other cached data in the backend untouched. This refreshes configurations or content without disrupting other Magento instances or applications sharing the same cache system.
• cache:flush completely empties the entire cache storage: all entries—Magento-related or not—are deleted. This is a more radical command that forces Magento to rebuild everything, which can temporarily slow down the site until the cache regenerates.

Key Takeaways:

• Use cache:clean for routine updates (layouts, configs, etc.)—it’s faster and less risky.
• Reserve cache:flush for persistent issues or major updates, as it wipes all cached data, including other applications’ cache if the backend is shared.
• You can also clean or flush specific cache types to target only what’s needed and avoid unnecessary slowdowns.
• Custom cache types can be created for specific development needs.

Warning: The config cache takes the longest to regenerate. Avoid purging it too often, whether in local or production environments.

setup:upgrade – What It Actually Does

The setup:upgrade command is critical when evolving your Magento project:

• Re-reads all db_schema.xml files to update the database schema.
• Executes setup patch data (data migration scripts—not to be confused with content).
• Reads module.xml files and updates app/etc/config.php (module order affects global behavior).
• Clears the cache, generated files, and static assets. To skip regenerating these, use the --keep-generated flag.

Good to Know:
The setup:db:status command should tell you if setup:upgrade is needed, but in practice, it almost always claims an update is required, even when it’s not.

Best Practices for Development & Deployment

In Development:

• Layout changes: Flush only the layout cache (or disable it locally, along with all caches except config).
• di.xml modifications: Flush the config cache (unavoidably slow).
• LESS file updates: Clean static files and var/view_preprocessed.
• New controller: Flush the cache (Magento stores metadata critical for controller functionality).
• Controller changes (constructor): Clean only the generated folder.
• PHP block/template edits: No action needed if Full Page Cache (FPC) is disabled (recommended for dev).
• DB schema changes or data patches: Run setup:upgrade with --keep-generated to save time.

In Production:

• Post-deployment: Flush the cache.
• During deployment: Run setup:upgrade (often with --keep-generated, since statics are pre-generated in CI).
• If issues arise: Flushing the Full Page Cache (FPC) alone often suffices. Avoid global cache purges in production to prevent performance hits.

Flush, clean ou Upgrade ?

Mastering when to use cache:clean, cache:flush, and setup:upgrade saves precious time in development and avoids unnecessary slowdowns in production. Tailor your commands to the situation to optimize your Magento 2 workflow.