v2.15.1
v2.15.0
What’s Changed
✨ Enhancements
- add support of privileged attribute in
service.build
section by @glours in #10112 - introduce
--ignore-buildable
to ignore buildable images on pull by @ndeloof in #10134 - introduce
--no-attach
to ignore some service output by @ndeloof in #10137
🐛 Fixes
- don’t fail
logs
whendriver:none
is set by @ndeloof in #10107 - don’t assume os.Stdout and rely on dockerCLI.streams by @ndeloof in #10082
- service hash MUST exclude replicas by @ndeloof in #10109
- check service names based on project, not running containers by @ndeloof in #10111
- fix security opts support (seccomp and unconfined) by @ndeloof in #10110
- Fix empty file when using compose config in case of smaller source files by @rimelek in #10129
- Set
pullChanged
when setting--pull
oncompose up
by @laurazard in #10128 - Ignore not only auto-removed containers but also «removal in progress» for orphan containers by @gtardif in #10136
- limit build concurrency according to
--parallel
by @ndeloof in #10133
🔧 Internal
- add buildx plugin to e2e configuration directory by @glours in #10113
- cleanup framework.go from unnecessary debug logs by @glours in #10116
Changelog
- update compose-go by @ndeloof in #10106
- build(deps): bump github.com/docker/cli-docs-tool from 0.5.0 to 0.5.1 by @dependabot in #10127
New Contributors
- @rimelek made their first contribution in #10129
- @gtardif made their first contribution in #10136
Full Changelog: v2.14.2…v2.15.0
v2.14.2
v2.14.1
What’s Changed
✨ Enhancements
- introduce —parallel to limit concurrent engine calls by @ndeloof in #10030
- distinguish stdout and stderr in
up
logs by @ndeloof in #10070 - align
compose ps
output withdocker ps
by @ndeloof in #10065 - Add —include-deps to push command by @gferon in #10044
- introduce —timestamp option on compose up by @ndeloof in #10076
- apply uid/gid when creating secret from environment by @ndeloof in #10084
🐛 Fixes
- fix deadlock waiting for attached-dependencies by @ndeloof in #10029
- fix race condition collecting pulled images IDs by @ndeloof in #10051
- Don’t stop pull for images that can be built by @ndeloof in #10054
- Fix corner case when there’s no container to attach to by @ndeloof in #10058
- ContainerStart must run sequentially for engine to assing distinct ports within configured range by @ndeloof in #10067
- fix parsing of repository:tag by @ndeloof in #10072
- load project from files when explicitly set by user by @ndeloof in #10062
🔧 Internal
- port: improve error-handling if port not found by @milas in #10039
- check only running containers in after down tests of profiles e2e tests by @glours in #10049
- Cleanup tips from output by @thaJeztah in #10047
- added table of contents inside readme by @nitinmewar in #9883
- remove go.* from e2e tests directory by @glours in #10059
- Add scorecard GitHub action by @joycebrum in #9846
- resolve —env-file as absolute path by @ndeloof in #10074
- use StatusError from docker/cli, not «dockerd» by @thaJeztah in #10080
- use recently introduced
withSelectedServicesOnly
to reduce code duplication by @ndeloof in #10083
Changelog
- build(deps): bump go.opentelemetry.io/otel from 1.11.1 to 1.11.2 by @dependabot in #10045
- update to go1.19.4 by @thaJeztah in #10048
- build(deps): bump github.com/containerd/containerd from 1.6.10 to 1.6.12 by @dependabot in #10055
New Contributors
- @nitinmewar made their first contribution in #9883
- @joycebrum made their first contribution in #9846
- @gferon made their first contribution in #10044
Full Changelog: v2.14.0…v2.14.1
v2.14.0
What’s Changed
✨ Enhancements
- Add
oom_score_adj
field to service definition (#10019) - Add
mode
field fortmpfs
mount permissions (#10031)
🐛 Fixes
- Only stop services started by up when interrupted (#10028)
- Load implicit profiles for targeted services (#10025)
- Do not require
service.build.platforms
to be set if service.platform is set (#10017) - Use plain output during buildx image builds if
--ansi=never
is set (#10020) COMPOSE_IGNORE_ORPHANS
environment variable now behaves more consistently (#10035)- Fix image name separator in convert (#9904)
- Fix run on services using
network_mode: service:NAME
(#10036)
🔧 Internal
- Upgrade compose-go to v1.8.0 (#10031)
- Build with Go 1.19.3 (#10037)
- Change default branch for docs repository (#10016)
- Additional E2E test coverage and reliability improvements (#10025, #10032)
Changelog
- change the default branch of the doc repository by @glours in #10016
- configure buildx for plain output if —ansi=never has been set by @ndeloof in #10020
- useDockerDefaultOrServicePlatform fct should return service.platform if defined by @glours in #10017
- implement support for oom_score_adj by @ndeloof in #10019
- Fix grammatical issues by @umarfchy in #9997
- only stop services started by
up
on interruption by @ndeloof in #10028 - pass services list to projectOrName function to add profiles for targeted services by @glours in #10025
- Broken Link fixed in compose docs by @NitishKumar06 in #10000
- move image digests resolution to backend by @ndeloof in #10026
- fix»convert —images» output to right format by @Windforce17 in #9904
- use StringToBool to detect COMPOSE_IGNORE_ORPHANS by @ndeloof in #10035
- Fix replacing «service:x» with «container:y» by @i-ky in #10036
- test: speed up Cucumber stop test by @milas in #10032
- schema: add support for tmpfs.mode in mount definition by @milas in #10031
- ci: upgrade to Go 1.19.3 & bump deps by @milas in #10037
New Contributors
- @umarfchy made their first contribution in #9997
- @NitishKumar06 made their first contribution in #10000
- @Windforce17 made their first contribution in #9904
- @i-ky made their first contribution in #10036
Full Changelog: v2.13.0…v2.14.0
v2.13.0
What’s Changed
✨ Enhancements
- Add
--no-consistency
flag to convert command by @glours in #9976 - Add
--build
tocompose run
by @laurazard in #10007 - Display creation warnings from the engine by @glours in #9998
🐛 Fixes
- Map deploy.restart_policy.condition to engine values by @glours in #9944
- Add support of deploy.reservation.memory by @glours in #9947
- Use COMPOSE_PROFILES value only if no command line arg profiles used by @glours in #9906
- Check if a missing image won’t be build via a service declared in depends_on section by @glours in #9984
- Ignore error parsing container number label, just warn by @ndeloof in #10005
- Use platform defined by DOCKER_DEFAULT_PLATFORM when pulling and no service platform defined by @glours in #9999
🔧 Internal
- Remove uses of deprecated gotest.tools v2 by @thaJeztah in #9935
- Ci: update dependencies to latest by @milas in #9982
- Exclude issues with the
kind/feature
label from stale bot process by @glours in #9992
Bumps
- build(deps): bump github.com/stretchr/testify from 1.8.0 to 1.8.1 by @dependabot in #9945
- build(deps): bump github.com/containerd/containerd from 1.6.8 to 1.6.9 by @dependabot in #9949
- build(deps): bump github.com/containerd/containerd from 1.6.9 to 1.6.10 by @dependabot in #9995
- go.mod: update docker-credential-helpers v0.7.0 by @thaJeztah in #9936
Full Changelog: v2.12.2…v2.13.0
v2.12.2
v2.12.1
What’s Changed
🐛 Security Fixes
- update docker engine API to apply fix of CVE-2022-39253 by @glours in #9934
🔧 Internal
- Skip flaky test in CI
merge
workflow by @laurazard in #9933 - build(deps): bump go.opentelemetry.io/otel from 1.11.0 to 1.11.1 by @dependabot in #9937
Full Changelog: v2.12.0…v2.12.1
v2.12.0
v2.11.2
ℹ️ Upgrade Notes
- Updates on environment file syntax & interpolation: see #9879 🔖
- Setting
DOCKER_HOST
via.env
files is not supported in Compose v2
🐛 Fixes
- Prevent «invalid template» errors on valid environment variable values (#9806, #9746, #9704, #9294)
- Ensure new images from
docker compose build
are used (#9856) - Fix cross-architecture builds when
DOCKER_DEFAULT_PLATFORM
not set (#9866) - Fix intermittent conflict errors when using
depends_on
(#9014) - Clear service
CMD
when entrypoint is overridden (#9622)
🔧 Internal
- Reduced permissions for GitHub Actions CI jobs
- CI now runs on Windows & macOS including E2E tests via Docker Desktop
- Upgrade to compose-go v1.6.0
- Internal support for shell completion (not ready yet!)
What’s Changed
- Add
merge
GitHub Actions workflow to run tests on Windows and macOS runners by @laurazard in #9863 - configure default builder export when no build.platforms defined by @glours in #9862
- keep the platform defined, in priority, via DOCKER_DEFAULT_PLATFORM o… by @glours in #9866
- Remove support for
DOCKER_HOST
in.env
files by @milas in #9871 - clean service command if entrypoint is overrided in run command by @glours in #9836
- Add completion command and fix convert by @ulyssessouza in #9269
- ci: upgrade to compose-go v1.6.0 by @milas in #9876
- add more information when
service.platform
isn’t part ofservice.build.platforms
by @bkielbasa in #9868 - GitHub Workflows security hardening by @sashashura in #9874
- deps: fix race condition during graph traversal by @milas in #9878
New Contributors
- @bkielbasa made their first contribution in #9868
- @sashashura made their first contribution in #9874
Full Changelog: v2.11.1…v2.11.2
Project description
Docker Compose is a tool for running multi-container applications on Docker
defined using the Compose file format.
A Compose file is used to define how the one or more containers that make up
your application are configured.
Once you have a Compose file, you can create and start your application with a
single command: docker-compose up
.
Compose files can be used to deploy applications locally, or to the cloud on
Amazon ECS or
Microsoft ACI using
the Docker CLI. You can read more about how to do this:
- Compose for Amazon ECS
- Compose for Microsoft ACI
Where to get Docker Compose
Windows and macOS
Docker Compose is included in
Docker Desktop
for Windows and macOS.
Linux
You can download Docker Compose binaries from the
release page on this repository.
Using pip
If your platform is not supported, you can download Docker Compose using pip
:
pip install docker-compose
Note: Docker Compose requires Python 3.6 or later.
Quick Start
Using Docker Compose is basically a three-step process:
- Define your app’s environment with a
Dockerfile
so it can be
reproduced anywhere. - Define the services that make up your app in
docker-compose.yml
so
they can be run together in an isolated environment. - Lastly, run
docker-compose up
and Compose will start and run your entire
app.
A Compose file looks like this:
services: web: build: . ports: - "5000:5000" volumes: - .:/code redis: image: redis
You can find examples of Compose applications in our
Awesome Compose repository.
For more information about the Compose format, see the
Compose file reference.
Contributing
Want to help develop Docker Compose? Check out our
contributing documentation.
If you find an issue, please report it on the
issue tracker.
Releasing
Releases are built by maintainers, following an outline of the release process.
Download files
Download the file for your platform. If you’re not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Pick Your Operating System
You came here to ask, «how do I install Docker?» The answer can be straightforward if you’re willing to accept my way, but the steps differ based on which operating system is utilized. To make things more complicated, there are a few ways to install Docker on your OS that are largely based on preference. Today I’m going to walk you through my preferred method. This isn’t the only way, but I’ve found it to be the best way to get up and running with ease. For Ubuntu, we’ll be setting up the Docker Engine. For Windows and macOS, we’ll be using Docker Desktop.
Click on any of the links below to get started with installing Docker.
- Installing Docker on Ubuntu
- Installing Docker Compose on Ubuntu
- Automated Installation Script for Linux (Ubuntu)
- Installing Docker Desktop on macOS
- Installing Docker Desktop on Windows and WSL2
Installing Docker on Ubuntu
For Ubuntu, we’re going to install Docker Engine and Docker Compose using the Docker and Compose repositories. This also happens to be the recommended approach by Docker.
Follow Along on YouTube
Set Up
- Delete any prior versions if you had installed them.
sudo apt-get remove docker docker-engine docker.io containerd runc
- Update your system and install the necessary dependencies.
sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release
- For security purposes, add Docker’s official GPG key. Read more about that here.
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
- Set up the stable repository.
echo
"deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
That’s quite a few steps, but if you followed along exactly, you should be ready to install Docker!
Installation
- Install the latest version of Docker, along with its dependencies.
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io
If you are running a later version of Ubuntu than what Docker has official builds for, you may get the following
error during this step.
Reading package lists... Done
Building dependency tree
Reading state information... Done
Package docker-ce is not available, but is referred to by another package.
This may mean that the package is missing, has been obsoleted, or
is only available from another source
E: Package 'docker-ce' has no installation candidate
E: Unable to locate package docker-ce-cli
E: Unable to locate package containerd.io
E: Couldn't find any package by glob 'containerd.io'
E: Couldn't find any package by regex 'containerd.io'
But don’t worry! We’ll just need to go install the latest version that is available. This can be done with the
following command INSTEAD of the one above.
sudo apt-get install -y docker.io
- Verify your install by running your first image.
sudo docker run hello-world
- Add your user as an admin to the Docker user group.
sudo usermod -aG docker $USER
Doing this last step means you no longer have to append sudo
to run Docker commands!
Uninstall
Fed up with Docker on your Ubuntu box? Uninstall and remove the configuration files with the following commands.
sudo apt-get purge docker-ce docker-ce-cli containerd.io
sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd
Installing Docker Compose on Ubuntu
Install
You must have completed the installation of Docker Engine in the steps above before you can install Docker Compose. Assuming you’ve done so without any errors, let’s continue on!
- Download the stable release of Docker compose.
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
Unlike the installation for Docker Engine where it automatically installs the latest version, Docker Compose has to have the version manually specified. At the time of writing, the latest version is 1.29.2
. The latest version can be viewed at the Compose repository release page on GitHub. Feel free to substitute the version in the command above as needed.
- Make the downloaded binary executable.
sudo chmod +x /usr/local/bin/docker-compose
Uninstall
To remove Docker Compose, utilize the following command (assuming you installed with curl
as we did above).
sudo rm /usr/local/bin/docker-compose
Automated Installation Script for Linux (Ubuntu)
An automated installation script can be found here. The contents are pasted below.
#!/bin/sh
echo "Starting docker community edition install..."
echo "Removing any old instances of docker and installing dependencies"
apt remove -y docker docker-engine docker.io containerd runc
apt update
apt install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common
echo "Dowloading latest docker and adding official GPG key"
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | apt-key add -
echo "Pulling the latest repository"
add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
apt update
echo "Installing docker community edition"
apt install -y docker-ce docker-ce-cli containerd.io
echo "Docker install completed, installing docker-compose"
echo "Dowloading docker-compose 1.29.2 - be sure to update to the latest stable"
curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o
/usr/local/bin/docker-compose
echo "Setting binary permissions"
chmod +x /usr/local/bin/docker-compose
echo “Docker and docker-compose install complete”
# Run docker as non-root user on Ubuntu
sudo usermod -aG docker $USER
Installing Docker Desktop on macOS
Note that Docker Desktop comes pre-equipped with Docker Engine, Docker Compose, Kubernetes, and a few other goodies.
Installation
Intel or Apple Silicon
Depending on which chipset you have on your Mac, you’ll need to install one of two versions of the Docker Desktop application. As this is a GUI application, there’s not much needed other than navigating to the correct site and installing the .dmg file. Just drag and drop the Docker icon into your Applications
directory.
Docker for macOS with Intel
The official link for installing Docker Desktop for macOS with an Intel chipset can be found here.
Apple Silicon
We’ll also need to take a few prior steps to get Docker Desktop running with Apple Silicon. Namely, you’ll need to install Rosetta 2 with the following command.
softwareupdate --install-rosetta
Afterward, install Docker Desktop for macOS with an Apple Silicon chipset from here.
Uninstall
Within the Docker Desktop toolbar item, navigate to the menu > Troubleshoot
> Uninstall
. See the screenshot below.
Installing Docker Desktop on Windows and WSL2
Note that Docker Desktop comes pre-equipped with Docker Engine, Docker Compose, Kubernetes, and a few other goodies. Firstly, you will need Docker Desktop even if you want Docker to only run on WSL. This is due to the sandboxed nature of WSL.
Installation
Windows
- First, you’ll need to ensure that virtualization is enabled for your CPU in the BIOS. This differs amongst motherboard manufacturers and chipsets (namely Intel and AMD). A quick Google search will get you going though.
- The executable for Docker Desktop for Windows can be found here. It can also be found on Docker Hub. Click the installer, follow the prompts and wait for it to be downloaded.
- During the process, be sure to allow the prompts for
Enable Hyper-V Windows Features
and theInstall required Windows components for WSL 2
.
WSL2
You’ll need to complete the steps for installing Docker Desktop on Windows before you can utilize WSL2. However, once you’ve completed it, feel free to come back to this section.
- Enable
Use the WSL2 based engine
in the Docker Desktop for Windows settings andApply & Restart
.
- Be sure that WSL2 is set as your default and current distribution.
Check the current WSL mode.
If not set to v2, upgrade your existing Linux.
wsl.exe --set-version (distro name) 2
Set v2 as the default version.
wsl.exe --set-default-version 2
- Navigate to
WSL Integration
and make sureEnable Integration with my default WSL distro
is checked.
Uninstall
Docker Desktop can be uninstalled from the Apps & features system settings. Just search for Docker Desktop
and select Uninstall
. Follow the prompts.
More Questions or Need Help
Be sure to check out the official documentation for Docker Engine and Docker Desktop and if you have more questions, feel free to send a message with any of the media icons below!
Docker Compose is available on multiple platforms.In this lab we’ll demonstrate some of the ways to install it on Linux, Windows and Mac.
Installing Docker Compose on Linux
Installing Docker Compose on Linux is a two-step process. Firt you will be downloading binary from github, Second giving executable permission.
Download the current stable release of Docker Compose
$ curl -L https://github.com/docker/compose/releases/download/1.24.1/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
$ chmod +x /usr/local/bin/docker-compose
Test the installation
You can run this command from a terminal window
$ docker-compose --version
Installing Docker Compose on Windows 10
If you have already installed Docker Desktop for Windows or Docker Toolbox then no need of separate installation for docker compose, since its part of the package.
Check Docker Compose is installed
You can run this command from a PowerShell or CMD terminal.
Installing Docker Compose on Mac
Docker Compose is installed as part of Docker for Mac. So if you have Docker for MAC, you have Docker Compose.
Check Docker Compose is installed
You can run this command from a terminal window.
$ docker-compose --version
Contributor
Savio Mathew
Update 2021: docker-compose has been rewritten in Go, and is now a docker command docker compose
As such, there is no longer the need to «install» it.
See docker compose
.
Update 7th of november 2018:
On desktop systems like Docker for Mac and Windows, Docker Compose is
included as part of those desktop installs.
Accordingly to the documentation, Docker for Windows and Docker Toolbox already include Compose along with other Docker apps, so most Windows users do not need to install Compose separately.
Update 2017: this is now officially managed (for Windows 10 supporting Hyper-V) with «Docker for Windows».
See «Install Docker for Windows».
It does have a chocolatey installation package for Docker, so:
choco install docker-for-windows
# or
choco upgrade docker-for-windows
Again, this requires a 64bit Windows 10 Pro, Enterprise and Education (1511 November update, Build 10586 or later) and Microsoft Hyper-V.
For other Windows, you still need VirtualBox + Boot2Docker.
Update: docker compose 1.5 (Nov 2015) should make it officially available for Windows (since RC2).
Pull requests like PR 2230 and PR 2143 helped.
Commit 13d5efc details the official Build process for the Windows binary.
Original answer (Q1-Q3 2015).
Warning: the original answer («docker-compose
in a container») below seems to have a bug, according to Ed Morley (edmorley
).
There appear to be caching issues with the «docker-compose in a container» method (See issue #6: «Changes to docker-compose.yml and Dockerfile not being detected»)
Ed recommends:
As such for now, running the Python
docker-compose
package insideboot2docker
seems to be the most reliable solution for Windows users (having spent many hours trying to battle with the alternatives).To install docker-compose from PyPI, run this from inside
boot2docker
:docker@boot2docker:~$ tce-load -wi python && curl https://bootstrap.pypa.io/get-pip.py | sudo python - && sudo pip install -U docker-compose
To save having to run the above every time the
boot2docker
VM is restarted (since changes don’t persist), you can usebootlocal.sh
like so:docker@boot2docker:~$ echo 'su docker -c "tce-load -wi python" && curl https://bootstrap.pypa.io/get-pip.py | python - && pip install -U docker-compose' | sudo tee /var/lib/boot2docker/bootlocal.sh > /dev/null && sudo chmod +x /var/lib/boot2docker/bootlocal.sh
(The
su docker -c
gymnastics are required sincetce-load
cannot be run asroot
, andbootlocal.sh
is run asroot
. Thechmod
ofbootlocal.sh
should be unnecessary once #915 is fixed.
Add-a
to thetee
command if you need to append, rather than overwritebootlocal.sh
.)If you wish to use a pre-release version of docker-compose, then replace
pip install -U docker-compose
withpip install -U docker-compose>=1.3.0rc1
or equivalent.
Original answer:
I also run docker-compose
(on Windows boot2docker) in a image by:
-
cloning https://github.com/docker/compose in
/c/Users/<username>/myproject/compose
(in order to have persistence, since/c/Users/<username>
is automatically mounted, when I use VirtualBox with its extension pack ) -
building the docker-compose image:
cd /c/Users/<username>/myproject/compose # that will put the repo in a detached HEAD, but it does not matter here git checkout 1.2.0 docker build -t docker-compose .
-
adding a ‘
dc
‘ alias (in aprofile
file that I copy to my/home/docker/.ashrc
before launching the boot2docker ssh session.)dc='docker run --rm -i -t -v /var/run/docker.sock:/var/run/docker.sock -v `pwd`:`pwd` -w `pwd` docker-compose'
From there, a ‘dc up
‘ or ‘dc ps
‘ just works. On Windows. With boot2docker 1.6.
8 November, 2022
1,600 words, 8-minute read
Docker can be installed on Linux, mac OS, or Windows.
Requirements and installation instructions can be found on the Docker Docs help pages.
Install Docker on Linux #
Docker Desktop for Linux can be downloaded from Docker Hub. The installer includes the Docker server, CLI, Docker Compose, Docker Swarm, and Kubernetes.
Alternatively, the Docker command-line tool is available in official Linux repositories although these are often older editions. The latest edition is supported on recent 64-bit editions of popular Linux distros:
- Ubuntu (and derivatives such as Mint)
- CentOS
- Debian
- Fedora
Static binaries are available for other distros, although Googling “install Docker on [your OS]” may provide easier instructions, e.g. “install Docker on a Raspberry Pi”.
Follow the Docker documentation for your distro. For example, Docker for Ubuntu is installed with the following commands:
sudo apt-get remove docker docker-engine docker.io containerd runc
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin
To run Docker commands as a non-root user (without sudo
), create and add yourself to a docker
group:
sudo groupadd docker
sudo usermod -aG docker $USER
Then reboot to apply all changes.
Install Docker on macOS #
Docker Desktop for macOS Sierra 10.13 and above can be downloaded from Docker Hub. The package includes the Docker server, CLI, Docker Compose, Docker Swarm, and Kubernetes.
Two editions are available: stable and edge with experimental features. The stable version is best for most developers.
Double-click Docker.dmg
to open the installer, then drag the Docker icon to the Applications folder. Double-click Docker.app in that folder to launch Docker.
After completion, the whale icon in the status bar indicates Docker is running and commands can be entered in the terminal.
Install Docker on Windows #
Docker Desktop for Windows requires either WSL2 or Hyper-V.
Windows Subsystem for Linux (WSL) 2 #
WSL allows you to run full Linux environments directly on Windows 10 or Windows 11.
IMPORTANT!
You can not install the Linux edition of Docker within a WSL-powered Linux distro. You must install Docker Desktop for Windows which allows Docker commands to be run in all Windows and Linux terminals.
WSL2 is the recommended default option for Docker on Windows. It is faster than Hyper-V and available in all editions of Windows 11 and Windows 10 from the May 2020 update (version 2004, OS build 19041).
To install WSL2:
-
Enable hardware virtualization support in your BIOS.
This will be active on most devices, but check by rebooting and accessing your PC’s BIOS panels – typically by hitting DEL, F2, or F10 as your system starts. Look for Virtualization Technology, VTx or similar options. Ensure they are enabled, save, and reboot.
WARNING! Be careful when changing BIOS settings – one wrong move could trash your PC.
-
Enable the Virtual Machine Platform and Windows Subsystem for Linux options in the Turn Windows features on or off panel:
This can be accessed by hitting the Start button and typing the panel name or from Programs and Features in the classic Control Panel.
-
Reboot, then enter the following command in a Windows Powershell or
cmd
prompt to set WSL2 as the default:wsl --set-default-version 2
-
Download and install your preferred distro by searching for “Linux” in the Microsoft Store app. Ubuntu is a good choice.
-
To complete the installation, launch your distro by clicking its Store’s Launch button or choosing its icon from the Start menu.
You may be prompted to install a kernel update – follow the instructions and launch the distro again.
-
Enter a Linux username and password. These are separate from your Windows credentials although choosing the same ones can be practical.
-
Ensure your distro is up-to-date. For example, on an Ubuntu bash prompt enter:
sudo apt update && sudo apt upgrade
You can now install Docker Desktop (see below). For the best performance and stability, store development files in your Linux file system and run Docker from your Linux terminal.
More information about installing and using WSL2:
- Windows Subsystem for Linux 2: The Complete Guide, and
- optionally, Windows Terminal: The Complete Guide.
Hyper-V #
The Microsoft Hyper-V hypervisor is provided free with Windows 10 and 11 Professional and Enterprise. (Windows Home users must use WSL2.)
To install Hyper-V:
-
Enable hardware virtualization support in your BIOS.
This will be active on most devices, but check by rebooting and accessing your PC’s BIOS panels – typically by hitting DEL, F2, or F10 as your system starts. Look for Virtualization Technology, VTx or similar options. Ensure they are enabled, save, and reboot.
WARNING! Be careful when changing BIOS settings – one wrong move could trash your PC.
-
Enable the Hyper-V option in the Turn Windows features on or off panel then reboot.
This can be accessed by hitting the Start button and typing the panel name or from Programs and Features in the classic Control Panel.
You can now install Docker Desktop.
Install Docker Desktop for Windows #
Docker Desktop for Windows 10 and 11 can be downloaded from Docker Hub. The installer includes the Docker server, CLI, Docker Compose, Docker Swarm, and Kubernetes.
Two editions are available: stable and edge with experimental features. The stable version is best for most developers.
Double-click Docker Desktop Installer.exe
to start the installation process. After completion and launch, the whale icon in the notification area of the task bar indicates Docker is running and ready to accept commands in the Windows Powershell/cmd
terminal (and Linux if using WSL2).
Docker Engine Settings #
Docker uses WSL2 as the default engine when available. You will be prompted to confirm this choice during installation and after WSL2 is installed.
Alternatively, WSL2 can be enabled by checking Use the WSL 2 based engine in the General tab of Settings accessed from the Docker task bar icon. Unchecking the option reverts to Hyper-V.
When using WSL2, at least one Linux distro must be enabled – the default is chosen. You can also permit Docker commands in other distros by accessing the WSL integration panel in the Resources section of the Docker Settings:
When using Hyper-V, Docker must be granted access to the Windows file system. Select the drives it is permitted to use by accessing the File Sharing panel in the Resources section of the Docker Settings:
(This option was named Shared Drives in previous editions of Docker Desktop.)
Test your Docker installation #
Check Docker has successfully installed by entering the following command in your terminal:
docker version
A response similar to the following is displayed:
Client: Docker Engine - Community
Version: 19.03.12
API version: 1.40
Go version: go1.13.10
Git commit: abcdef0
Built: Mon Jun 22 15:45:36 2020
OS/Arch: linux/amd64
Experimental: false
Server: Docker Engine - Community
Engine:
Version: 19.03.12
API version: 1.40 (minimum version 1.12)
...etc...
Ensure Docker Compose is working by entering:
docker-compose version
To receive something like:
docker-compose version 1.27.2, build 8d51620a
docker-py version: 4.3.1
CPython version: 3.7.7
OpenSSL version: OpenSSL 1.1.1c 10 Sep 2019
Optionally, try entering:
docker run hello-world
to verify Docker can pull an image from Docker Hub and start containers as expected…
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
1b930d010525: Pull complete
Digest: sha256:f9dfddf63636d84ef479d645ab5885156ae030f611a56f3a7ac
Status: Downloaded newer image for hello-world:latest
Hello from Docker!
This message shows your installation appears to be working correctly.
Key points #
What you’ve learned in this chapter:
- How to install and configure Docker on your Linux, macOS, or Windows system.
- How to install Docker Compose.
- How to test the Docker installation.
The following chapters demonstrate how to use Docker during development…
…but to continue reading, you need to buy the book.
Do you want an easy-to-follow course which demonstrates how to use Docker and create practical web development environments on your Windows, macOS, or Linux PC?
Buy the «Docker for Web Developers» book & video course…
-
full course
$99 $50 £43 / €49
buy all
-
ebooks only
$30 $15 £13 / €15
buy books
-
videos only
$80 $40 £34 / €40
buy videos
plus your country’s sales tax where applicable