go-away-docker

Overview

Powershell script that deletes the C:\ProgramData\Docker directory

Warning: This comes at the cost of losing your Windows images, containers, volumes, and docker engine state. You are starting fresh and will need to re-pull your images and recreate your containers and volumes.

Why Do This?

Complete Uninstall

You're done with Docker Desktop (congratulations). You've uninstalled it. It's left behind gigabytes of now useless data on your file system.

Docker Windows Engine Is Not Starting

Windows updates, power loss, disk error, antivirus scanners, or all of the above are able to corrupt image layers in C:\ProgramData\Docker.

You attempt to start Docker in windows container mode or switch to windows container mode while docker is running and the sad cycle begins.

1. windows engine starts up
2. starts enumerating layers in C:\ProgramData\Docker
3. tries to validate each layer's reparse points
4. hits broken link in corrupted layer
5. dies
6. docker desktop reports that it failed to start the docker engine and prompts you to quit the application

To rectify this problem you need to remove the corrupted layers. In theory you could go in with a scalpel and identify and remove just the corrupted data, but it's easier to opt for the big hammer and remove C:\ProgramData\Docker all together. Docker will replace it with a healthy directory the next time it runs and your windows engine will work again.

Why Not Delete It Manually?

If you've found this script you've likely tried to delete C:\ProgramData\Docker normally to discover that you don't have permission, regardless of whether you run with elevated privileges, change folder permissions, change the owner and so on.

Turns out C:\ProgramData\Docker is created using the Windows Host Compute System (HCS) to benefit from special filesystem features like reparse points. It needs to be deleted using the HCS.

What Does This Script Do?

1. Takes a path to a docker image layer directory, default is C:\ProgramData\Docker
2. Checks that Docker isn't running
3. Verifies the path is a docker directory
4. Calls HcsDestroyLayer from the official Host Computer System API to safely remove the folder.

References

https://learn.microsoft.com/en-us/virtualization/api/hcs/overview

https://learn.microsoft.com/en-us/virtualization/api/hcs/reference/apioverview

https://learn.microsoft.com/en-us/virtualization/api/hcs/reference/tutorial

https://learn.microsoft.com/en-us/windows-hardware/drivers/ifs/reparse-points