Migrating from Docker Toolbox to Docker for Mac

Overview

Docker for Mac has become the prefered method for running Docker on Mac based systems. Docksal, Lando and Docker themselves are pushing this as the standard going forward. If you're running an older Mac (before 2010) or OS lower than OS X El Capitan 10.11, then you should use (or continue to use) Docker Toolbox. If your system meets the minimum requirements for Docker for Mac and you've previously setup your system using Docker Toolbox, the steps below will guide you through the process of migrating (or fresh installing) Docker for Mac.

Migration Steps

Note: The following steps are only required if you've previously installed and are using Docker Toolbox in your current setup. If you do not already have Docker Toolbox and Virtualbox setup on your system, feel free to skip ahead to Step 4.

Step 1: Migrating from Docker Toolbox to Docker for Mac (Optional, but reccomended)

If you'd like to migrate any Toolbox images from your original Docker installation to use on Docker for Mac you can follow Dockers guide that will assist you in doing so. Use the link below to find Docker's step by step migration guide. Please note that a script will take care of the majority of the migration/conversion process for you and will require having Homebrew already installed and updated on your system.

• https://docs.docker.com/docker-for-mac/docker-toolbox/#migrating-from-docker-toolbox-to-docker-for-mac

Step 2: Uninstall Docker Toolbox

The next step will be to remove your old Toolbox instance and can be done so by following Docker's uninstallation guide below.

• https://docs.docker.com/toolbox/toolbox_install_mac/#how-to-uninstall-toolbox

Step 3: Uninstall VirtualBox (optional)

After Docker Toolbox has been removed, you can optionally remove Virtualbox too. This isn't a required step, but if you're only use of Virtual Box was for Docker this guide below will help clean up your system.

• https://nektony.com/how-to/uninstall-virtualbox-on-mac

Step 4: Download & Install Docker for Mac

If you're getting Docker setup on your new system or your migrating from Docker Toolbox you'll first need to download and install Docker for Mac. You can download the .DMG directly from Docker's website using the link below and following the installation instructions that come packaged.

• https://www.docker.com/docker-mac

Step 5: Install Docksal (optional)

Note: If you have already installed Docksal previously, feel free to skip this step and continue onto Step 6.

• https://docs.docksal.io/en/master/getting-started/env-setup/#macos

Step 6: Configure Docksal to use Docker for Mac

Having Docksal installed on your system, you'll now need to configure it to use Docker for Mac. Those steps can be found by following the link below.

• https://docs.docksal.io/en/master/getting-started/env-setup-native/#switching-to-docker-for-macwindows

Troubleshooting

Xdebug Fix

There is an issue with Docksal and Docker for Mac that stops Xdebug from functioning correctly. The link below is reference to a discussion on github that will help resolve/patch the problem until it is fix in Docksal core.

• https://github.com/docksal/docksal/issues/389