Welcome to Docker for Mac!
Docker is a full development platform for creating containerized apps, and Docker for Mac is the best way to get started with Docker on a Mac.
Already have Docker for Mac? If you already have Docker for Mac installed, and are ready to get started, skip down to Step 2. Check versions of Docker Engine, Compose, and Machine to work through the rest of the Docker for Mac tour, or jump over to getting started tutorials at Learn Docker.
If you have not already done so, please install Docker for Mac. You can download installers from the stable or beta channel. For more about stable and beta channels, see the FAQs.
|Stable channel||Beta channel|
|This installer is fully baked and tested, and comes
with the latest GA version of Docker Engine along with experimental features in Docker Engine, which are enabled by
default and configurable on Docker Daemon preferences for experimental mode.
This is the best channel to use if you want a reliable platform to work with. (Be sure to disable experimental features for apps in production.)
These releases follow a version schedule with a longer lead time than the betas, synched with Docker Engine releases and hotfixes.
On the stable channel, you can select whether to send usage statistics and other data.
|This installer provides the latest Beta release of
Docker for Mac, offers cutting edge features along with
experimental features in Docker Engine, which are enabled by
default and configurable on Docker Daemon preferences for experimental mode.
This is the best channel to use if you want to experiment with features under development, and can weather some instability and bugs. This channel is a continuation of the beta program, where you can provide feedback as the apps evolve. Releases are typically more frequent than for stable, often one or more per month.
We collect all usage data on betas across the board.
Get Docker for Mac (stable)
Download checksum: Docker.dmg SHA256
Get Docker for Mac (beta)
Download checksum: Docker.dmg SHA256
Docker for Mac requires OS X El Capitan 10.11 or newer macOS release running on a 2010 or newer Mac, with Intel’s hardware support for MMU virtualization. The app will run on 10.10.3 Yosemite, but with limited support. Please see What to know before you install for a full explanation and list of prerequisites.
You can switch between beta and stable versions, but you must have only one app installed at a time. Also, you will need to save images and export containers you want to keep before uninstalling the current version before installing another. For more about this, see the FAQs about beta and stable channels.
defaultmachine (if one exists) to the new Docker for Mac HyperKit” VM. When you are running Docker for Mac, you do not need Docker Machine nodes running at all locally (or anywhere else). With Docker for Mac, you have a new, native virtualization system running (HyperKit) which takes the place of the VirtualBox system. To learn more, see Docker for Mac vs. Docker Toolbox.
Note: If your system does not satisfy these requirements, you can install Docker Toolbox, which uses Oracle VirtualBox instead of HyperKit.
Docker.dmg to open the installer, then drag Moby the whale to
the Applications folder.
You will be asked to authorize
Docker.app with your system password during
the install process. Privileged access is needed to install networking
components and links to the Docker apps.
Docker.app to start Docker.
The whale in the top status bar indicates that Docker is running, and accessible from a terminal.
If you just installed the app, you also get a success message with suggested next steps and a link to this documentation. Click the whale ) in the status bar to dismiss this popup.
Click the whale () to get Preferences and other options.
Select About Docker to verify that you have the latest version.
Congratulations! You are up and running with Docker for Mac.
Run these commands to test if your versions of
docker-machine are up-to-date and compatible with
$ docker --version Docker version 1.13.0-rc3, build 4d92237 $ docker-compose --version docker-compose version 1.9.0, build 2585387 $ docker-machine --version docker-machine version 0.9.0-rc2, build 7b19591
Note: The above is an example. Your output will differ if you are running different (e.g., newer) versions.
Open a command-line terminal, and run some Docker commands to verify that Docker is working as expected.
Some good commands to try are
docker version to check that you have the
latest release installed, and
docker ps and
docker run hello-world to
verify that Docker is running.
For something more adventurous, start a Dockerized web server.
docker run -d -p 80:80 --name webserver nginx
If the image is not found locally, Docker will pull it from Docker Hub.
In a web browser, go to
http://localhost/ to bring up the home page.
(Since you specified the default HTTP port, it isn’t necessary to append
:80 at the end of the URL.)
Note: Early beta releases used
dockeras the hostname to build the URL. Now, ports are exposed on the private IP addresses of the VM and forwarded to
localhostwith no other host name set. See also, Release Notes for Beta 9.
docker ps while your web server is running to see details on the
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 56f433965490 nginx "nginx -g 'daemon off" About a minute ago Up About a minute 0.0.0.0:80->80/tcp, 443/tcp webserver
Stop or remove containers and images.
nginx webserver will continue to run in the container on that port
until you stop and/or remove the container. If you want to stop the
docker stop webserver and start it again with
start webserver. A stopped container will not show up with
docker ps; for
that, you need to run
docker ps -a.
To stop and remove the running container with a single command, type:
docker rm -f webserver. This will remove the container, but not the
nginx image. You can list local images with
docker images. You might
want to keep some images around so that you don’t have to pull them again
from Docker Hub. To remove an image you no longer need, use
docker rmi followed by an image ID or image name. For example,
docker rmi nginx.
Want more example applications? - For more example walkthroughs that include setting up services and databases in Docker Compose, see Example Applications.
Choose –> Preferences from the menu bar. You can set the following runtime options.
Docker for Mac is set to automatically start Docker when you log in. Uncheck this option if you don’t want Docker to start when you open your session.
Docker for Mac is set to automatically check for updates and notify you when an update is available. If an update is found, click OK to accept and install it (or cancel to keep the current version). If you disable the check for updates, you can still find out about updates manually by choosing -> Check for Updates
Check Exclude VM from Time Machine backups to prevent Time Machine from backing up the Docker for Mac virtual machine.
Send usage statistics — You can set Docker for Mac to auto-send diagnostics, crash reports, and usage data. This information can help Docker improve the application and get more context for troubleshooting problems. Uncheck this to opt out and prevent auto-send of data. Docker may prompt for more information in some cases, even with auto-send enabled. Also, you can enable or disable these auto-reporting settings with one click on the information popup when you first start Docker.
You can decide which directories on your Mac to share with containers.
Add a Directory - Click
+ and navigate to the directory you
want to add.
Click Apply & Restart to make the directory available to
containers using Docker’s bind mount (
There are some limitations on the directories that can be shared:
They cannot be a subdirectory of an already shared directory.
They cannot already exist inside of Docker.
See Namespaces in the topic on osxfs file system sharing for more information.
Tip: File sharing is required for volume mounting if the project lives outside of the
/Usersdirectory. In that case, share the drive where the Dockerfile and volume are located. Otherwise, you will get file not found or cannot start service errors at runtime. (See also Volume mounting requires file sharing for any project directories outside of
By default, Docker for Mac is set to use 2 processors. You can increase processing power for the app by setting this to a higher number, or lower it to have Docker for Mac use fewer computing resources.
By default, Docker for Mac is set to use
2 GB runtime memory, allocated from
the total available memory on your Mac. You can increase the RAM on the app to
get faster performance by setting this number higher (for example to
1) if you want Docker for Mac to use less memory.
You can specify the storage location of the Linux volume; i.e., where containers and images are stored.
Starting with Beta 39, storage image is referred to as disk image, and is tracked by the app. If you attempt to move the disk image to a location that already has one, you will get a prompt asking if you want to use the existing image or replace it. For Beta releases going forward, the labels on this dialog were updated as follows.
Docker for Mac will detect HTTP/HTTPS Proxy Settings and automatically propagate
these to Docker and to your containers. For example, if you set your proxy
http://proxy.example.com, Docker will use this proxy when pulling
You can configure options on the Docker daemon that determine how your containers will run. You can configure some Basic options on the daemon with interactive settings, or switch to Advanced to edit the JSON directly.
The settings offered on Basic dialog can be configured directly in the JSON as well. This version just surfaces some of the commmon settings to make it easier to configure them.
Starting with Stable 1.13.0 and Beta 31, both Docker for Mac Stable and Beta releases have experimental features enabled on Docker Engine, as described in the Docker Experimental Features README on GitHub.
Experimental features are not appropriate for production environments or workloads. They are meant to be sandbox experiments for new ideas. Some experimental features may become incorporated into upcoming stable releases, but others may be modified or pulled from subsequent Betas, and never released on Stable.
On both Beta and Stable releases, you can toggle experimental mode on and off. If you toggle it off, Docker for Mac uses the current generally available release of Docker Engine.
You can check whether you are running experimental mode or not by typing
version on the command line. Experimental mode is listed under
true, then Docker is running in experimental mode, as
shown here. (If
false, Experimental mode is off.)
$ docker version Client: Version: 1.13.0-rc3 API version: 1.25 Go version: go1.7.3 Git commit: 4d92237 Built: Tue Dec 6 01:15:44 2016 OS/Arch: darwin/amd64 Server: Version: 1.13.0-rc3 API version: 1.25 (minimum version 1.12) Go version: go1.7.3 Git commit: 4d92237 Built: Tue Dec 6 01:15:44 2016 OS/Arch: linux/amd64 Experimental: true
As an alternative to using Docker Hub to store your public or private images or Docker Trusted Registry, you can use Docker to set up your own insecure registry. Add URLs for insecure registries and registry mirrors on which to host your images. (See also, How do I add custom CA certificates? in the FAQs.)
On the Daemon -> Advanced dialog, you can directly configure the daemon from the JSON file, and determine entirely how your containers will run. For a full list of options on the Docker daemon, see daemon in the Docker Engine command line reference.
After editing the daemon configuration , click Apply & Restart to save it and reboot Docker. Or, to cancel changes, click another preference tab, then choose to discard or not apply changes when asked.
Choose –> Preferences from the menu bar, then click Uninstall / Reset on the Preferences dialog.
Uninstall - Choose this option to remove Docker for Mac from your system.
Reset to factory defaults - Choose this option to reset all options on Docker for Mac to its initial state, the same as when it was first installed.
You can uninstall Docker for Mac from the command line with this command:
<DockerforMacPath> --uninstall. If Docker is installed in the default
location, the following command will provide a clean uninstall.
$ /Applications/Docker.app/Contents/MacOS/Docker --uninstall Docker is running, exiting... Docker uninstalled successfully. You can move the Docker application to the trash.
You might want to use the command-line uninstall if, for example, you find that the app is non-functional, and you cannot uninstall it from the menu.
If you are using
homebrew bash-completion on Mac
bash completion scripts for the following commands may be found inside
Docker.app, in the
To activate bash completion, these files need to be copied or symlinked to your
bash_completion.d/ directory. For example, if you use
ln -s /Applications/Docker.app/Contents/Resources/etc/docker.bash-completion /usr/local/etc/bash_completion.d/docker ln -s /Applications/Docker.app/Contents/Resources/etc/docker-machine.bash-completion /usr/local/etc/bash_completion.d/docker-machine ln -s /Applications/Docker.app/Contents/Resources/etc/docker-compose.bash-completion /usr/local/etc/bash_completion.d/docker-compose
To get help from the community, review current user topics, join or start a discussion, log on to our Docker for Mac forum.
To report bugs or problems, log on to Docker for Mac issues on GitHub, where you can review community reported issues, and file new ones. See Diagnose problems, send feedback, and create GitHub issues. As a part of reporting issues on GitHub, we can help you troubleshoot the log data.
To give us feedback on the documentation or update it yourself, use the Feedback options at the bottom of each docs page.
Try out the tutorials and sample app walkthroughs at Learn Docker, including:
Learn Docker basics in Getting Started with Docker
Learn how to define and deploy a Docker stack to a swarm (deploy multiple containers as services and use new Compose Version 3 features)
Dig in deeper with Docker Labs example walkthroughs and source code.
For a summary of Docker command line interface (CLI) commands, see Docker CLI Reference Guide.
Check out the blog post Introducing Docker 1.13.0.