osteel's blog Web development resources

Docker for local web development, appendix A: Docker on Windows

Been here before?
This content is deprecated

As usual things are moving fast with Docker, and since I started writing and publishing this series Microsoft released Windows Subsystem for Linux version 2 (WSL 2). Essentially, it allows Linux containers to run natively on Windows, without emulation, meaning overall performance should be much, much better. See the installation guide on Windows here and how to configure Docker Desktop to use it here.

This is now the preferred way to use Docker on Windows and I do not recommend you follow the instructions below anymore. I simply leave them here for reference, in case some people still rely on them. I may take this page down altogether at some point in the future.

Docker on Windows

In this series

Subscribe to email alerts at the end of this article or follow me on Twitter to be informed of new publications.

In this post

Why this appendix?

You might have heard some rumours claiming Docker is a bit of a pain to run on Windows. The bad new is these rumours are mostly true. All is not lost, however: most hurdles come with little tricks that, once known and applied, make the experience of Docker on Windows almost the same as a Unix-based system.

This appendix is about those little tricks, which should allow you to complete the entirety of this tutorial series and run the final result smoothly on Microsoft's OS.

Note that this appendix is not about Windows-based containers.

Minimum requirements

Docker cannot run on any version of Windows. The minimum requirements are listed in the Docker documentation and, at the time of writing, they indicate your system should run at least Windows 10 64-bit Pro, Enterprise, or Education, because of Docker's virtualisation needs.

Docker Desktop

If you haven't already, download and install Docker Desktop, which is essentially a virtual machine running Docker and Docker Compose.

Make sure not to tick Use Windows containers instead of Linux containers during installation.

Virtualisation, Hyper-V and VirtualBox

Docker requires hardware virtualisation capabilities to function properly, which on Windows are provided for by Hyper-V. If your system satisfies the aforementioned requirements, Hyper-V is probably already enabled; if Docker seems to think otherwise, head over here for instructions about how to activate it.

Once Hyper-V is running, you might notice that VirtualBox doesn't work anymore: it is essentially because Hyper-V transforms Windows into a virtual machine on which VirtualBox cannot run. As a result, you can't use Docker and VirtualBox at the same time, and you will need a system restart to switch from one to the other (this also applies to other level 2 hypervisors like VMware).

Having said this, you may not have to choose between the two: what you need VirtualBox for may also be compatible with Hyper-V (like Homestead, for instance).

If you are interested in the subject, you can read more about virtualisation on Windows, and about the conflicts between Hyper-V and VirtualBox.


The people at Docker seem to be focusing on Docker Desktop's UI at the moment, and I wouldn't be surprised if everything we currently do in a terminal ends up being available on the dashboard. For the time being, however, using a terminal is still (and will most likely always be, in my opinion) the easiest way to use Docker.

To be able to follow this tutorial series in optimal conditions, you will need a command line interface featuring Bash, for which I recommend using Git Bash, whose name is rather indicative of what it ships with. You will then be able to run regular Docker commands and execute some Bash scripts when we get to that.

You need to pay attention to a couple of options while installing the software. The first one is about line endings, for which you should select Checkout as-is:

Git line endings

If you don't, you will run into trouble when we get to using Bash scripts.

The other one is the terminal emulator:

Git console window

Make sure to select Use Windows' default console window; if you don't, you will have to prepend any Docker command with winpty. This is a long standing issue that makes using the albeit nicer MinTTY a pain, although it seems Windows' console has improved with Windows 10 (source).

If you also intend to clone the GitHub repository coming with the series, you can run Git commands from the same terminal, provided an SSH key is set up. If you already use a GIT GUI like GitKraken, you can skip this part; otherwise, open Git Bash and run the following command:

$ ls -l ~/.ssh

If you don't see a couple of files named id_rsa and id_rsa.pub or if the folder doesn't exist, run the following command and hit return at every prompt:

$ ssh-keygen -o

This will basically generate a public/private RSA key pair so Git Bash can interact with GitHub via SSH.

Run the following command to display your public key and copy the result:

$ cat ~/.ssh/id_rsa.pub

Paste it as a new SSH key in your GitHub settings.

Your Git Bash is now set!

"Ok, but terminal XYZ is better" I know there are other terminals for Windows out there (you can even run a proper Linux distribution on Windows 10, apparently), and if you are already using one that you are satisfied with, by all means keep using it. This guide is mostly intended for people who are not sure where to start, and to whom I suggest a fairly simple solution that I know works.

Local folder and disk sharing

You will need to share the local drive containing your Docker projects with Docker, which you can do in the application's settings.

Note that based on your Docker Desktop version, you might get prompted for your account's password and an empty string won't be accepted. Meaning if you don't have a password for your account, you will probably have to set one first.


The local setup needs ports 80 and 443 to be available, but the former might already be in use (which will most likely prevent the Nginx container from starting properly).

A quick way to free up the port is to run the following command as admin (from Command Prompt, not from Git Bash):

$ net stop http /y

If you still have issues, have a look at this article.

Based on the way you intend to access the database, you might also need to free up port 3306 (unless you plan on using phpMyAdmin).

SSL/TLS certificates

It is not possible to install self-signed SSL/TLS certificates (used by this series from part 5 via the command line, so Windows users will have to do it manually.

Thankfully, it is not overly complicated and this tutorial does a good job at laying out the different steps.

Other resources and fixes

If you encounter other issues, some of these resources might help:

Something missing?

This guide should be enough to get you going with this tutorial series; that being said, I work on a Mac and don't have regular access to a Windows machine, so if anything seemingly Microsoft-related happens I won't be of much assistance.

If you come across an issue and find a way to solve it, please let me know in the comments and I will consider amending this guide. Pull requests are also always welcome.

All set? You can now proceed with the first part of this series.

Enjoying the content?

Last updated by osteel on :: [ tutorial docker windows ]