298

I've just upgraded to Windows 10 Home May 2020, activated WSL2, and installed Docker Desktop.

WSL2 must be installed in my system disk, which is a small SSD. I don't want to fill it with docker images. How do I change the docker images path? I'd like to use a path in my big Windows filesystem.

The image location is somewhat confusing. I believe it is in /mnt/wsl/docker-desktop-data/.

How do I change the directory of docker images inside WSL2? May I change docker configuration to select a path inside /mnt/d, or mount a path from /mnt/d over docker data dirs?

questionto42
  • 7,175
  • 4
  • 57
  • 90
neves
  • 33,186
  • 27
  • 159
  • 192

11 Answers11

719

The WSL 2 docker-desktop-data vm disk image would normally reside in: %USERPROFILE%\AppData\Local\Docker\wsl\data\ext4.vhdx

Follow the following to relocate it to other drive/directory, with all existing docker data preserved (tested against Docker Desktop 2.3.0.4 (46911), and continued to work after updating the 3.1.0 (51484)):

First, shut down your docker desktop by right click on the Docker Desktop icon and select Quit Docker Desktop

Then, open your command prompt:

wsl --list -v

You should be able to see, make sure the STATE for both is Stopped.(wsl --shutdown)

  NAME                   STATE           VERSION
* docker-desktop         Stopped         2
  docker-desktop-data    Stopped         2

Export docker-desktop-data into a file

wsl --export docker-desktop-data "D:\Docker\wsl\data\docker-desktop-data.tar"

Unregister docker-desktop-data from wsl, note that after this, your ext4.vhdx file would automatically be removed (so back it up first if you have important existing image/container):

wsl --unregister docker-desktop-data

Import the docker-desktop-data back to wsl, but now the ext4.vhdx would reside in different drive/directory:

wsl --import docker-desktop-data "D:\Docker\wsl\data" "D:\Docker\wsl\data\docker-desktop-data.tar" --version 2

Start the Docker Desktop again and it should work

You may delete the D:\Docker\wsl\data\docker-desktop-data.tar file (NOT the ext4.vhdx file) if everything looks good for you after verifying

orad
  • 15,272
  • 23
  • 77
  • 113
Franks CHOW
  • 7,206
  • 1
  • 10
  • 5
  • 40
    Perfect! I wanted to use my HDD instead of SSD for docker images. This was what I was looking for. – Wajahath Sep 14 '20 at 06:56
  • 4
    Perfect. The only add-on I can add to this thread, is that I had just purged my cache, and I didn't had this docker-desktop-data present on listing, so I had to start Docker again and quit it in order to create the docker-desktop-data WSL distro again. – Danton Heuer Oct 05 '20 at 04:43
  • 16
    Note that you will also need to shutdown wsl before exporting (I got a TimeoutException without that) : `wsl --shutdown`. – Julian Didier Oct 19 '20 at 08:24
  • 8
    I suffered from low disk space for so long ... Thank you a lot ! – Disappointed Nov 09 '20 at 15:58
  • But I still have a huge file `C:\Users\Public\Documents\Hyper-V\Virtual hard disks\DockerDesktop.vhdx` Can I delete it after ? – Disappointed Nov 09 '20 at 16:09
  • 1
    Is there a way to do the same on new images? I mean the images which we'll pull later. – Indranil Gayen Nov 20 '20 at 21:14
  • 1
    Thank you! It worked for me. And for those who have a virtual machine in hyper-v-manager. It cannot belong to docker with wsl 2. It must be something from a previous version. – arnisz Dec 31 '20 at 12:29
  • What, if anything, can be deleted after completing these steps and verifying results? – Micah Zoltu Feb 18 '21 at 05:13
  • 1
    Since the original `%USERPROFILE%\AppData\Local\Docker\wsl\data\ext4.vhdx` has already been automatically removed when you "unregister", what's left would be the docker-desktop-data.tar as mentioned in the answer. – Franks CHOW Feb 18 '21 at 10:16
  • 2
    In my case at the end of the procedure - after running the command for importing docker-desktop-data.tar to the new location - the WSL did not turn back on automatically (`wsl --list -v` was still showing results in a "stopped" state) and apparently there was no way to make WSL start again. As a result Docker Desktop could not find its image, so I tried restarting its service, which did not help either, as it was not enough to trigger WSL to turn itself back on... At last, I rebooted my system and when I restarted Docker Desktop it finally ran properly, along with WSL, and found its image... – Redoman May 01 '21 at 22:58
  • 2
    Also worked for windows 11 – Amin Shojaei Oct 16 '21 at 19:55
  • 12
    I had problems related to 'The system cannot find the path specified.', Solved by creating directory 'D:\Docker\wsl\data' directory before procedure. – Sergey Dvoreckih Dec 09 '21 at 17:07
  • How to clean old data in drive c to free space? – Ali Sherafat Dec 29 '21 at 05:03
  • 1
    It doesn't work for me. After I did these steps, Docker Desktop is endless starting. – Neshta Jan 11 '22 at 12:01
  • 1
    In my case it works... but when i use the "Clean / Purge data" option from the docker desktop client (under troubleshoot) than the vdhx is resetted to the old location. Any ideas how do i prevent this? It should clean and purge and recreate the vdhx at the new location... – gischy Jul 13 '22 at 14:27
  • 1
    Confirmed working with Docker v4.10.1 – Haidar Zeineddine Jul 21 '22 at 08:22
  • in case you are getting "A distribution with the supplied name already exists." just be sure you executed "wsl --unregister docker-desktop-data" as in post – Nigrimmist Sep 04 '22 at 18:39
  • cool it works fine. I have found very similar blog with same description. follow steps and worked. will upvote a response how it exactly works as it expected for 'linux container' on Windows. – Damiani Sep 29 '22 at 13:54
  • 1
    Note: You can now copy over your vhdx and use `--import-in-place` to import it, rather than having to export and import. Just a bit more streamlined. – Kobato Nov 24 '22 at 02:55
  • This works fine but in my case somehow kubernetes stops working after these changes – Abdul Mohsin Jan 24 '23 at 14:17
  • Note: If you have multiple distros make sure ALL of them are stopped not just `docker-desktop*`. Else you'll get an error: `Unspecified error Error code: Wsl/Service/E_FAIL` – Joseph Mar 06 '23 at 04:48
  • Tested in Docker Desktop 4.19.0 (106363) -- it works! – naXa stands with Ukraine May 19 '23 at 03:36
53
  1. Stop Docker Desktop
  2. Relocate Docker folder from C:\Users\xxx\AppData\Local\Docker to new path
  3. Make sure C:\Users\xxx\AppData\Local\Docker is no longer there
  4. Open a cmd in administrator mode
  5. Run the following command that will create a symbolic link in the cmd window with the appropriate from and to path
    mklink /j "C:\Users\xxx\AppData\Local\Docker" "path to where you relocated your docker folder"
  1. Restart Docker Desktop
dejanualex
  • 3,872
  • 6
  • 22
  • 37
Attila Badi
  • 531
  • 4
  • 3
22

Edit: re-register docker-desktop would set the default docker-data to C drive now, so we should only unregister docker-data as the accepted answer.

You can do

 wsl --unregister docker-desktop-data

 wsl --import docker-desktop-data D:\wsl\docker-desktop-data "C:\Program Files\Docker\Docker\resources\wsl\wsl-data.tar" --version=2

The tar file is the file used to install, and before it is your new destination.

This always work while the move-wsl or lxrunoffline didn't work for me on fast rings. And sometimes you have to unistall/install docker first

Yiming Lu
  • 361
  • 2
  • 5
13

Extending @Attila Badi 's answer would be to also give the same treatment to the C:\ProgramData\Docker folder, which seems to be used for WSL / Windows Containers. Even moving the Docker data folders, would still leave you with a boot drive ProgramData\Docker folder of massive proportions - especially if you are unable or unwilling to clean the images. You cannot migrate it, or move it once installed. Using the Docker engine advanced settings works in Linux container mode, but not in windows and vice versa and has trouble starting.

Steps I followed:

  1. Uninstall Docker. I know... Make sure you have saved what you need.

  2. Create the primary space-eating docker folders, in a location you have a lot of space, e.g. :

    D:\Data\Docker\ProgramData_Docker & D:\Data\Docker\AppData_Local_Docker

  3. Create linked folders, by running the below in a command window in administrator mode:

mklink /j "C:\Users\xxx\AppData\Local\Docker" "D:\Data\Docker\ProgramData_Docker"
mklink /j "C:\ProgramData\Docker" "D:\Data\Docker\AppData_Local_Docker"
  1. Install Docker.

You should be able to merrily pull windows server images, but not clog up your boot drive.

UPDATE:

Trying to symlink the C:\ProgramData\Docker folder, may result in a security error, depending on the version running depending on the originally installed version.

Release notes for 4.13.0 refers to this feature, which my be a possible work-around (Thanks to @bhagerty and @Oly for the trail):

 start /w “” “Docker Desktop Installer.exe” install --installation-dir=G:\Docker

(Source: ungureanuovidiu @ https://forums.docker.com/t/docker-installation-directory/32773/17 )

Update:

This works on 4.17.1 BUT ProgramData_Docker changes to DockerDesktop. Broken Everything required a windows reset and reinstalling docker on windows 11 with the above changes still work / apply. NB remember the DocherDesktop change after one of the versions.

Anthony Horne
  • 2,522
  • 2
  • 29
  • 51
  • 1
    I was trying to avoid this approach but looks like from all the ones I tried this one worked for me. I think My problem is that I'm using new docker but in WSL1 setup and the 2021 answers do not apply on me. And the locations were slightly different, I did only one link here: mklink /j "C:\ProgramData\DockerDesktop" "D:\work\docker" – Anton Krug Apr 29 '21 at 11:36
  • @AntonKrug I am running WSL 2 on an insider windows slow ring. – Anthony Horne Apr 29 '21 at 12:48
  • 1
    I'm on WIN10 LTSC which so far has only the WSL1, so then docker put things into slightly different folders and moving folders was not possible for me even when I shutdown Docker/Hyper-V. But when I uninstalled, prepared the C:\ProgramData\DockerDesktop -> D drive link then just installed Docker again then it did exactly what I wanted – Anton Krug Apr 29 '21 at 13:48
  • 2
    Agreed. Shutdown did nothing for me either - it still runs WSL machines in the background somewhere. Glad it worked for you. Docker should fix this and make it property part of settings (advanced even). – Anthony Horne Apr 30 '21 at 10:29
  • 4
    It's ridiculous that it's not part of the regular install already, docker is not for casual consumers, yet power users often have elaborate partions/hdds setups, so I would say Docker should have this as an option for long time. Actually one of the reasons why I still use other frameworks like vagrant which feel much more solidly build and designed. – Anton Krug Apr 30 '21 at 10:40
  • 1
    Not working with Docker Desktop. Installation stops with an error: For security reasons c:/ProgramData/DockerDesktop can not by symlink. – Oly Nov 16 '22 at 01:12
  • @Oly Did you run this in administrator mode? – Anthony Horne Nov 16 '22 at 15:37
  • 1
    As of November 2022, Docker will let you relocate the **user** directory with a junction or a symlink, but not the `C:\ProgramData\DockerDestop` directory. You get the error @Oly pointed out. It's not an issue of running in admin mode. – bhagerty Nov 27 '22 at 22:17
  • @bhagerty I am running the latest (2022-11-17) with the symlinks . Although not ideal, you could install one prior and then run the update. I will investigate other options. – Anthony Horne Nov 28 '22 at 09:17
  • 1
    `start /w “” “Docker Desktop Installer.exe” install --installation-dir=G:\Docker` is NOT a workaround. This only installs the Docker Desktop program to that folder, not the docker images and containers. Those data are still left at %USERPROFILE%\AppData\Local\Docker\wsl\data\ext4.vhdx – Valorad Dec 07 '22 at 22:18
10

For me docker won't start with junction.

Then I've used just directory symbolic link:

Docker stopped

Folder "wsl" moved to other location on disk "B"

RUben@AD-RUBEN C:\Users\RUben\AppData\Local\Docker
$ mklink /D wsl "B:\dev\wsl"
**symbolic link** created for wsl <<===>> B:\dev\wsl

enter image description here

Containers and Images are ready to use:

enter image description here

RUben
  • 201
  • 2
  • 6
  • 2
    FreeMove utility can do this with a GUI for the lazy ones: https://github.com/imDema/FreeMove – djibe Jun 06 '22 at 15:19
  • 1
    This concept plus the suggested FreeMove utility made this operation absolutely dead-simple - everything worked perfectly first try. If anyone wants the easy answer, this is it. – bsplosion Jul 22 '23 at 16:56
4

A nice tool:

DDoSolitary/LxRunOffline: A full-featured utility for managing Windows Subsystem for Linux (WSL)

https://github.com/DDoSolitary/LxRunOffline

LxRunOffline.exe move    Move a distribution to a new directory.
Options:
  -n arg                Name of the distribution
  -d arg                The directory to move the distribution to.

for example:

quit docker desktop, then:

wsl --shutdown
LxRunOffline.exe move -n docker-desktop-data -d D:\vm\dockerdesktop\wsl\data
Xingxing Qiao
  • 146
  • 6
4

The best option is to update the registry. Follow the below steps

  1. Shutdown the wsl. Use the command wsl --shutdown.
  2. Move the entire C:\Users\%USERPROFILE%\AppData\Local\Docker directory to different drive for example D:\Docker.
  3. Goto Registry editor location Computer\HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss.
  4. Find the registry entry with the BasePath set to C:\Users\%USERPROFILE%\AppData\Local\Docker\wsl\data. Update this D:\Docker\wsl\data.
  5. Find another registry entry with the BasePath set to C:\Users\%USERPROFILE%\AppData\Local\Docker\wsl\distro. Update this D:\Docker\wsl\distro.
  6. Restart wsl using: wsl -d Ubuntu.
Maxim Kamalov
  • 745
  • 9
  • 23
Subramanya Adiga
  • 93
  • 1
  • 7
  • I wasn't able to move distro with current Docker version. It just restores it in the old place after restart – Basil Peace Mar 02 '23 at 04:42
  • And, if you move the entire Docker directory then you should change Docker configuration as well, not just Lxss. Probably add execRoot into C:\Users\%USERPROFILE%\.docker\daemon.json – Basil Peace Mar 02 '23 at 05:16
3

I found this tool from pxlrbt on github. It's using standard wsl import/export and pretty safe. Just moved both my docker-desktop-data distro to a different drive and it works well.

sidecus
  • 732
  • 5
  • 10
  • 2
    After I moved using the above script, I got an error `Docker desktop WSL distro stopped`. Mind to share the steps? – otong Aug 17 '20 at 17:07
2

Just for reference for anyone finding this question, as of now (June 2023):

  1. The export-import method fails on Windows for images larger than 8 GB. It's a bug in the underlying tar implementation.

  2. Fortunately, there is a --vhd switch for wsl that one can use for export and import. Even more, there is a wsl --import-in-place command that is useful when one has large volumes.

  3. Although moving the wsl .vhdx files to another location works from the wsl point of view, Docker Desktop still has problems with it. After it makes changes to "docker-data", e.g., the (smaller) distro\ext4.vhdx file, Docker Desktop finally deletes this volume and even a backup copy at the old (%APPDATA%\Docker\wsl\distro) location, and pops an error window.

All in all, I second the mklink method on Windows as 1. it's the least hassle, 2. it's working.

Yogurt
  • 83
  • 9
1

In Windows 10 home, docker desktop creates the VM under ""C:\Users\xxx\AppData\Local\Docker" directory and it is this VM that contains the downloaded docker images. If you want to change the VM location from C: to a different directory you can do this by creating a junction on windows (prior to docker desktop installation) using a command like below:

mklink /j "C:\Users\xxx\AppData\Local\Docker" "D:\Users\xxx\AppData\Local\Docker"

Note that prior to executing the command the target directory structure should exist while you should delete the C:\Users\xxx\AppData\Local\Docker directory if it exists already else the command could fail. Now install docker desktop on windows 10 home and voila you can see stuff inside "D:\Users\xxx\AppData\Local\Docker" directory namely the docker VM hard disk image file that is going to contain all the downloaded docker images.

Anupam Yadav
  • 13
  • 4
1

Using small SSD also you may want to relocate WSL swap file location.

https://learn.microsoft.com/en-us/windows/wsl/wsl-config

hotamateurxxx
  • 23
  • 4
  • 2
    Your answer could be improved with additional supporting information. Please [edit] to add further details, such as citations or documentation, so that others can confirm that your answer is correct. You can find more information on how to write good answers [in the help center](/help/how-to-answer). – Community Jun 05 '22 at 06:08
  • 2
    This does not provide an answer to the question. Once you have sufficient [reputation](https://stackoverflow.com/help/whats-reputation) you will be able to [comment on any post](https://stackoverflow.com/help/privileges/comment); instead, [provide answers that don't require clarification from the asker](https://meta.stackexchange.com/questions/214173/why-do-i-need-50-reputation-to-comment-what-can-i-do-instead). - [From Review](/review/late-answers/31943824) – Besworks Jun 07 '22 at 21:59