Configure where Multipass stores external data

[since version 1.11.0]

This document demonstrates how to configure the location where Multipass caches images, stores instances, and other user information.

Contents:

Configuring a new storage location

Configuring a new storage location can be useful, for example, if you need to free up storage space on your boot partition.

Caveats:

  • Multipass will not migrate your existing instances or clean up previously cached images after they expire. Therefore, you will have to re-download any Ubuntu images and reinitialise any VM instances that you need. On Windows, this sometimes means that the Multipass service will be unable to authenticate the client. If this happens and you are unable to authenticate with a passphrase, then you need to copy over the data from the old location to the new one.

    1. Stop the Multipass service from the Windows Services Manager
    2. Copy over everything from in the old Multipass directory to the new one. (The default Multipass storage directory is C:\ProgramData\Multipass)
    3. Start the Multipass service

  • Subsequently, when uninstalling Multipass, the uninstaller will not remove data stored in custom locations which must be deleted manually.

Linux

Firstly, stop the Multipass daemon:

$ sudo snap stop multipass

Depending on where the new storage directory is located you will need to connect the respective interface to the Multipass snap. Because of snap confinement, this directory needs to located in either /home or one of the removable mounts points:

$ sudo snap connect multipass:removable-media  # for /mnt or /media
$ sudo snap connect multipass:all-home  # for /home/*

Then, create the new directory:

$ mkdir -p <path>
$ sudo chown root <path>

Finally, create the override config file replacing <path> with the absolute path of the directory created above and restart the Multipass daemon.

$ sudo mkdir /etc/systemd/system/snap.multipass.multipassd.service.d/
$ sudo tee /etc/systemd/system/snap.multipass.multipassd.service.d/override.conf <<EOF
[Service]
Environment=MULTIPASS_STORAGE=<path>
EOF
$ sudo systemctl daemon-reload
$ sudo snap start multipass

macOS

On macOS, execute the following commands as root replacing <path> with the absolute path of the new storage location:

$ launchctl stop /Library/LaunchDaemons/com.canonical.multipassd.plist
$ tee /Library/LaunchDaemons/setenv.MULTIPASS_STORAGE.plist <<\EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>setenv.MULTIPASS_STORAGE</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/sh</string>
    <string>-c</string>
    <string>
      if [ -z "$( /bin/launchctl getenv MULTIPASS_STORAGE )" ]; then
        /bin/launchctl setenv MULTIPASS_STORAGE "<path>"
        /bin/launchctl unload /Library/LaunchDaemons/com.canonical.multipassd.plist
        /bin/launchctl load /Library/LaunchDaemons/com.canonical.multipassd.plist
      fi
    </string>
  </array>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>
EOF
$ launchctl load /Library/LaunchDaemons/setenv.MULTIPASS_STORAGE.plist

Windows

On Windows, open an administrator privileged PowerShell prompt and execute the following commands replacing <path> with the absolute path of the new storage location:

PS> Stop-Service Multipass
PS> Set-ItemProperty -Path "HKLM:System\CurrentControlSet\Control\Session Manager\Environment" -Name MULTIPASS_STORAGE -Value "<path>"
PS> Start-Service Multipass

Reverting back to the default location

Linux

$ sudo snap stop multipass

Although not required, to make sure that Multipass does not have access to directories that it shouldn’t, disconnect the respective interface depending on where the custom storage location was set.

$ sudo snap disconnect multipass:removable-media  # for /mnt or /media
$ sudo snap disconnect multipass:all-home  # for /home/*

Then, remove the override config file and restart the Multipass daemon.

$ rm /etc/systemd/system/snap.multipass.multipassd.service.d/override.conf
$ sudo systemctl daemon-reload
$ sudo snap start multipass

macOS

On macOS, execute the following commands as root:

$ launchctl stop /Library/LaunchDaemons/com.canonical.multipass.plist
$ rm /Library/LaunchDaemons/setenv.MULTIPASS_STORAGE.plist
$ launchctl load /Library/LaunchDaemons/setenv.MULTIPASS_STORAGE.plist

Windows

On Windows, execute the following commands with elevated permissions in PowerShell:

PS> Stop-Service Multipass
PS> Remove-ItemProperty -Path "HKLM:System\CurrentControlSet\Control\Session Manager\Environment" -Name MULTIPASS_STORAGE
PS> Start-Service Multipass

Let us know how this worked for you and what you’d like to see next!

Last updated 4 months ago.

Help improve this document in the forum.