This page describes how to restart and reset Cuttlefish virtual devices. Resetting a Cuttlefish device to its initial disk state is referred to as powerwashing in the command line tool.
When running automated or manual workflows with multiple different procedures, such as test suites, resetting the Cuttlefish device between procedures ensures that the behavior of each procedure is independent. If the disk state isn't reset, one procedure can affect the behavior of the following procedure.
The restart and reset procedures described on this page assumes that you have created a Cuttlefish device and have set some state on the disk.
# Launch a device
launch_cvd# Make some modifications to the device
adb shell touch /storage/self/primary/Documents/hello# Check the device state
adb shell ls /storage/self/primary/Documents
From this starting point, you can use the following restart and reset flows:
- If device is responsive, perform a clean restart using
- If device is unresponsive, perform an unclean restart using
- Reset the device state using
- Stop the device and change the
launch_cvdarguments while keeping the device state or forcibly clearing the device state.
Cuttlefish quick reset implementation
Cuttlefish uses a quick reset implementation that's dependent on protecting the disks behind qcow2 disk overlays. By default, Cuttlefish treats original disks as read-only and uses overlays to capture disk writes.
However there are drawbacks to using copy-on-write overlays. Notably, external changes to the underlying disks break compatibility with existing overlays, and cause an inconsistent disk state. Cuttlefish forcibly recreates the overlays when it detects incompatible changes.
Forcibly recreating the overlays is undesirable when developing a feature that requires keeping part of the disk in a particular initialized state while swapping out a different part of the disk. For example, installing an app with a particular user configuration and then repeatedly swapping out the kernel to test the interaction between the app and different kernel builds. In this case, it might be worth disabling the overlays.
The following sections describe ways to reset a Cuttlefish device to its initial disk state.
Reset one device
To reset one Cuttlefish device to its initial disk state, run:
powerwash_cvd shuts down the virtual machine, resets any changes made to the
virtual machine disk, restarts the virtual machine, and waits until it finishes
booting. The instance preserves the original flags given to
In a multi-tenant configuration,
powerwash_cvd restarts a single instance out of the instance group:
Reset all devices
To stop and reset one or more devices to their initial disk states, run:
stop_cvd performs an unclean shutdown and stops the device.
launch_cvd makes Cuttlefish destroy all files
related to the previously running instance before starting the next run. It's
safe to add any additional
In a multi-tenant configuration,
shuts down the entire instance group.
The following sections describe ways of restarting a device without resetting the device to its initial disk state.
To do a clean restart of the device when the device is responsive, run:
adb reboot takes the device through the full shutdown procedure, syncing
changes to the disk and making sure processes shut down. Cuttlefish host
processes aren't involved. This procedure could be unavailable if the device
has entered a bad state and become unresponsive.
To do a clean restart of a single Cuttlefish device in a
multi-tenant configuration, specify the
of the target device when running
adb-reboot. If no target device is
adb doesn't restart any device.
adb -s SERIAL reboot
To perform an unclean restart when the device is unresponsive, run:
restart_cvd performs an unclean shutdown by instantly shutting down the
restart_cvd is the equivalent of
disconnecting and reconnecting the battery to a physical device. Disk writes
might not persist if they were in progress.
restart_cvd waits until the device
has fully booted again before exiting.
In a multi-tenant configuration,
restart_cvd restarts a single instance out of the instance group. To specify
which Cuttlefish instance to restart, use the
--instance_num isn't used, the instance number defaults to
Restart using different launch_cvd flags
To stop one or more devices and relaunch with different
launch_cvd flags, run:
stop_cvd performs an unclean shutdown similar to
restart_cvd. It leaves the
device in a dormant state that can be started again later with a different
launch_cvd command. As with
restart_cvd, disk writes might not persist if
they aren't fully synced to the disk. To safely save data to disk, run
adb reboot first.
If changes to
launch_cvd flags force a change to the disk layout that's
incompatible with the copy-on-write implementation,
the old disk modifications and resets to the original disk state. For a full
list of flags, see Flags.
Run without an overlay
To opt out of quick-reset support, run:
--use_overlay=false treats the Cuttlefish disk files as read-write, and
changes are propagated into those files.
--use_overlay=false and the default can cause compatibility
errors. To forcibly clean up the prior device state, run:
rm $HOME/cuttlefish $HOME/cuttlefish_runtime $HOME/cuttlefish_assembly
Cuttlefish can't safely navigate the transition between the flows with and without overlays, so this change deletes all the Cuttlefish management state. If external disk files are modified and are reused later together with overlays, the earlier modifications are considered part of the baseline state.
You can add arguments using flags when launching a Cuttlefish device using
launch_cvd. However, for certain flags
(Flags that must stay the same), data loss can occur if flags are
launch_cvd commands. To ensure no data loss occurs when
running a sequence of commands that include
stop_cvd, and then
launch_cvd again, use the same flags for every
launch_cvd command. For
example, if the first
launch_cvd flag includes the argument
--kernel_path=KERNEL_PATH, the second
must also include the same
argument, or any file system changes made before
stop_cvd are lost in the
launch_cvd invocation. The file referenced by
KERNEL_PATH must also have the same contents.
Some flags are safe to change between
launch_cvd invocations. The following
sections list the flags that must stay the same to avoid data loss and flags
that can be safely changed without data loss. For details on individual flags,
refer to the source (
) or run
Flags that must stay the same
These flags must stay the same from one
launch_cvd invocation to the next to
avoid data loss:
Flags that can change
These flags can be safely changed between
launch_cvd invocations without
causing data loss: