Docker Machine with USB support on Windows/macOS

Docker 1.x logo

Docker Machine with USB support on Windows/macOS

The only way to make USB devices available in Docker containers under Windows or macOS is to use the Docker Machine that comes with the usual installer and uses VirtualBox. This is not needed on a Linux host OS with x86_64 architecture.

  • Download and install Docker for Windows or Docker for Mac (Docker Machine) from https://www.docker.com/products/docker.

  • Download and install VirtualBox 5.1+ from https://www.virtualbox.org/wiki/Downloads.

  • Optionally, to make flashing faster also download and install VirtualBox Extension Pack.

  • Initialize the Docker Machine as a virtual machine (VM) called default from the console:

$ docker-machine create --driver virtualbox default
Running pre-create checks...
(default) No default Boot2Docker ISO found locally, downloading the latest release...
(default) Latest release for github.com/boot2docker/boot2docker is v1.13.0
(default) Downloading /Users/ami/.docker/machine/cache/boot2docker.iso from https://github.com/boot2docker/boot2docker/releases/download/v1.13.0/boot2docker.iso...
(default) 0%....10%....20%....30%....40%....50%....60%....70%....80%....90%....100%
Creating machine...
(default) Copying /Users/ami/.docker/machine/cache/boot2docker.iso to /Users/ami/.docker/machine/machines/default/boot2docker.iso...
(default) Creating VirtualBox VM...
(default) Creating SSH key...
(default) Starting the VM...
(default) Check network to re-create if needed...
(default) Waiting for an IP...
Waiting for machine to be running, this may take a few minutes...
Detecting operating system of created instance...
Waiting for SSH to be available...
Detecting the provisioner...
Provisioning with boot2docker...
Copying certs to the local machine directory...
Copying certs to the remote machine...
Setting Docker configuration on the remote daemon...
Checking connection to Docker...
Docker is up and running!
To see how to connect your Docker Client to the Docker Engine running on this virtual machine, run: docker-machine env default
$ docker-machine ls
NAME      ACTIVE   DRIVER       STATE     URL                         SWARM   DOCKER    ERRORS
default   -        virtualbox   Running   tcp://192.168.99.100:2376           v1.13.0

  • Enable USB support in VirtualBox for your VM default:

    Note: If you installed the VirtualBox Extension Pack, apply the --usbxhci on option instead of --usb on .

$ docker-machine stop
Stopping "default"...
Machine "default" was stopped.
$ vboxmanage modifyvm default --usb on
$ #vboxmanage modifyvm default --usbxhci on
$ docker-machine start
Starting "default"...
(default) Check network to re-create if needed...
(default) Waiting for an IP...
Machine "default" was started.
Waiting for SSH to be available...
Detecting the provisioner...
Started machines may have new IP addresses. You may need to re-run the `docker-machine env` command.

  • One way to attach USB devices in your VM default is to add filter rules that automatically attach USB devices:

    Note: First command determines which USB devices are available on your host, following commands add filter rules that automatically attach USB devices with a matching vendor id and product id. Afterwards you will need to unplug and plug those USB devices back in (or restart your VM), to trigger the attach filters.

$ vboxmanage list usbhost
Host USB Devices:

UUID:               5b23cdc4-cfc7-49c4-81f6-844b1378cdf1
VendorId:           0x0403 (0403)
ProductId:          0x6001 (6001)
Revision:           6.0 (0600)
Port:               2
USB version/speed:  0/Full
Manufacturer:       FTDI
Product:            TTL232R-3V3
SerialNumber:       FTGI13S5
Address:            p=0x6001;v=0x0403;s=0x0000f62c7b7304f3;l=0x14212000
Current State:      Busy

$ vboxmanage usbfilter add 0 --target default --name 'FTDI TTL232R-3V3' --vendorid 0x0403 --productid 0x6001
  • Alternatively, you can attach USB devices manually:
    • open the VirtualBox application
    • find your VM default
    • select Show or double-click on it
    • wait for the VM window to show up
    • select Devices/USB from the menu and enable what devices you want to use from the host in the guest (and consequently in Docker containers)
  • If you want to tweak something in your VM default itself, you can SSH into it with:
$ docker-machine ssh

  • Activate correct environment to use the Docker Machine in VM default:

    Warning: Do not forget to run this each time you open a new console and want to begin using Docker!!!

$ eval "$(docker-machine env default)"
  • Now you are ready to use Docker.