DDEV Snapshot Guide: Creating and Restoring Local Environments

Local environments are safest when they can be reset quickly and predictably. In DDEV, snapshots provide a practical way to capture the state of a project database before risky work, then restore it when an update, migration, import, or experiment does not go as planned.

TL;DR: DDEV snapshots let you save and restore your local database state with simple commands. Use ddev snapshot --name snapshotname before major changes, and restore with ddev restore-snapshot snapshotname when needed. Snapshots are best used alongside Git, because they protect database state, not your full codebase or every project asset. Name snapshots clearly and create them before updates, migrations, content imports, or destructive tests.

What a DDEV Snapshot Is

A DDEV snapshot is a local backup of your project’s database state. It is designed for development workflows where you need a reliable rollback point before making changes that may affect content, configuration, schema, or imported data. For example, if you are testing a CMS upgrade, running a database migration, or importing a new dataset, a snapshot gives you a fast way to return to the previous state.

It is important to be precise: a DDEV snapshot is not the same as committing code to Git, nor is it a full disaster recovery system. Your theme files, custom modules, plugins, application code, and configuration files should still be managed through version control. Uploaded media and generated files may need separate backup handling depending on your project structure.

When You Should Create a Snapshot

Snapshots are most useful when there is a meaningful risk of changing the database in a way that is difficult to reverse manually. A disciplined snapshot habit can save hours of cleanup and prevent confusing local states that do not match the intended test scenario.

Create a snapshot before:

• Running CMS or framework updates, especially when database updates are involved.
• Executing migrations that alter tables, content models, fields, or configuration.
• Importing production or staging data into your local environment.
• Testing destructive operations, such as deleting content, users, orders, or taxonomy terms.
• Changing major dependencies that may trigger schema or configuration changes.
• Debugging complex bugs where you need to repeat the same scenario multiple times.

A snapshot is especially valuable when paired with a clean Git working tree. If your code is committed and your database is snapshotted, you can return both major parts of the local environment to a known state.

Preparing Your DDEV Project

Before creating a snapshot, confirm that your DDEV project is running and that the database is in the state you actually want to preserve. A rushed snapshot of a broken or half-migrated database is rarely useful.

Start your environment with:

ddev start

Then confirm that the application loads correctly in the browser or by using the project’s CLI tools. For a Drupal, WordPress, Laravel, TYPO3, or custom PHP project, this may include checking the homepage, logging into the admin interface, or running a basic command that confirms database connectivity.

It is also sensible to verify your code state:

git status

If you have uncommitted changes, decide whether they are intentional. DDEV snapshots will not replace good source control hygiene.

Creating a Snapshot

To create a snapshot, use the ddev snapshot command. Naming the snapshot is strongly recommended because clear names make restoration safer and easier later.

ddev snapshot --name before-upgrade

Use names that describe the reason for the snapshot, not just the date. A name like before-drupal-10-3-update or pre-product-import is much more useful than test1. In a busy project, poor naming leads to uncertainty, and uncertainty leads to accidental restores.

Good snapshot names include:

• before-composer-update
• pre-schema-migration
• before-client-content-import
• clean-install-after-config-import
• baseline-before-debugging-checkout-flow

After the command completes, DDEV stores the snapshot locally for that project. You can then proceed with your update, migration, or experiment with substantially less risk.

Restoring a Snapshot

If the work fails or you need to repeat the same test from the original state, restore the snapshot using:

ddev restore-snapshot before-upgrade

This operation replaces the current local database state with the state captured in the snapshot. Treat it as a destructive operation. Any database changes made after the snapshot was created can be lost when you restore it.

Before restoring, consider whether you need to preserve anything from the current database. If you are unsure, create another snapshot first:

ddev snapshot --name failed-upgrade-before-restore

Then restore the known good state:

ddev restore-snapshot before-upgrade

This approach gives you an additional safety net. Even failed states can be useful for debugging, comparing behavior, or reporting an issue later.

A Practical Workflow Example

Consider a project where you need to update dependencies and run database updates. A responsible workflow might look like this:

1. Start the project with ddev start.
2. Confirm the site works locally.
3. Check Git status and commit or stash unrelated code changes.
4. Create a snapshot: ddev snapshot --name before-dependency-update.
5. Run the dependency update, such as ddev composer update.
6. Run the project’s database update command.
7. Test the site thoroughly.
8. If the result is unacceptable, restore with ddev restore-snapshot before-dependency-update.

This pattern separates risk into manageable parts. Git protects your code history, while DDEV snapshots protect the local database state. Together, they support repeatable, professional local development.

Best Practices for Snapshot Management

Snapshots are easy to create, but they should still be managed intentionally. Over time, old snapshots can become confusing or consume unnecessary local disk space.

• Use descriptive names. A snapshot name should explain its purpose without needing extra notes.
• Create snapshots before risk, not after failure. The right moment is before the migration, update, or import begins.
• Do not confuse snapshots with deployment backups. They are local development tools, not a replacement for production backup policies.
• Coordinate with your team. If multiple developers are testing the same workflow, agree on baseline imports and snapshot naming conventions.
• Keep Git clean. Restoring a database snapshot while your code is in an unknown state can create misleading results.
• Remove obsolete snapshots periodically. Keep important baselines, but avoid accumulating unclear historical states.

Image not found in postmeta

Common Mistakes to Avoid

One common mistake is assuming a snapshot includes everything. It does not replace a repository, a file backup, or a production-grade recovery plan. If your work depends on uploaded files, generated assets, or private configuration outside the database, make sure those are handled separately.

Another mistake is restoring a snapshot while running code from a different branch. For example, restoring an older database while the application code expects a newer schema can produce errors that look like application bugs but are really state mismatches. When switching branches, consider whether the database should be restored to a matching snapshot.

Finally, avoid creating snapshots with vague names. In a serious development environment, clarity matters. A snapshot called before-taxonomy-refactor communicates intent; a snapshot called new does not.

Conclusion

DDEV snapshots are a simple but powerful safeguard for local development. They make risky work more controlled by allowing you to return to a known database state with a single restore command. Used correctly, they reduce downtime, support repeatable testing, and make complex changes less stressful.

The most reliable workflow is straightforward: keep code in Git, create a named DDEV snapshot before database-changing work, test carefully, and restore when necessary. With that discipline, your local environment becomes not only more convenient, but also more trustworthy.