2015-06-08 03:07:20 +00:00
<!-- [metadata]>
+++
title = "Installation on Windows"
description = "Docker installation on Microsoft Windows"
keywords = ["Docker, Docker documentation, Windows, requirements, virtualbox, boot2docker"]
[menu.main]
parent = "smn_engine"
+++
<![end-metadata]-->
2014-04-16 00:53:12 +00:00
# Windows
2014-05-26 01:52:57 +00:00
2015-07-12 14:09:14 +00:00
> **Note**: This release of Docker deprecates the Boot2Docker command line in
> favor of Docker Machine. Use the Docker Toolbox to install Docker Machine as
> well as the other Docker tools.
2014-06-09 00:36:49 +00:00
2015-07-12 14:09:14 +00:00
You install Docker using Docker Toolbox. Docker Toolbox includes the following Docker tools:
2015-03-27 21:54:37 +00:00
2015-07-12 14:09:14 +00:00
* Docker Machine for running the `docker-machine` binary
* Docker Engine for running the `docker` binary
* Kitematic, the Docker GUI
* a shell preconfigured for a Docker command-line environment
* Oracle VM VirtualBox
Because the Docker daemon uses Linux-specific kernel features, you can't run
Docker natively in Windows. Instead, you must use `docker-machine` to create and attach to a Docker VM on your machine. This VM hosts Docker for you on your Windows system.
The Docker VM is lightweight Linux virtual machine made specifically to run the
Docker daemon on Windows. The VirtualBox VM runs completely from RAM, is a
small ~24MB download, and boots in approximately 5s.
## Requirements
2015-08-22 05:06:11 +00:00
Your machine must be running Windows 7, 8/8.1 or newer to run Docker. Windows 10 is not currently supported. To find out what version of Windows you have:
2015-07-12 14:09:14 +00:00
2015-08-22 05:06:11 +00:00
1. Right click the Windows Start Menu and choose **System** .
2015-07-12 14:09:14 +00:00
![Which version ](/installation/images/win_ver.png )
2015-08-22 05:06:11 +00:00
If you are using an unsupported version of Windows, you should consider
upgrading your operating system in order to try out Docker.
2015-07-12 14:09:14 +00:00
2015-08-22 05:06:11 +00:00
2. Make sure your CPU supports [virtualization technology ](https://en.wikipedia.org/wiki/X86_virtualization )
and virtualzation support is enabled in BIOS and recognized by Windows.
2015-07-12 14:09:14 +00:00
#### For Windows 8 or 8.1
Choose **Start > Task Manager** and navigate to the **Performance** tab.
Under **CPU** you should see the following:
![Release page ](/installation/images/virtualization.png )
If virtualization is not enabled on your system, follow the manufacturer's instructions for enabling it.
2015-08-22 05:06:11 +00:00
#### For Windows 7
2015-07-12 14:09:14 +00:00
Run the < a
href="http://www.microsoft.com/en-us/download/details.aspx?id=592"
target="_blank"> Microsoft® Hardware-Assisted Virtualization Detection
Tool< / a > and follow the on-screen instructions.
> **Note**: If you have Docker hosts running and you don't wish to do a Docker Toolbox
installation, you can install the `docker.exe` using the *unofficial* Windows package
manager Chocolately. For information on how to do this, see [Docker package on
Chocolatey](http://chocolatey.org/packages/docker).
### Learn the key concepts before installing
In a Docker installation on Linux, your machine is both the localhost and the
Docker host. In networking, localhost means your computer. The Docker host is
the machine on which the containers run.
On a typical Linux installation, the Docker client, the Docker daemon, and any
containers run directly on your localhost. This means you can address ports on a
Docker container using standard localhost addressing such as `localhost:8000` or
`0.0.0.0:8376` .
![Linux Architecture Diagram ](/installation/images/linux_docker_host.svg )
In an Windows installation, the `docker` daemon is running inside a Linux virtual
machine. You use the Windows Docker client to talk to the Docker host VM. Your
Docker containers run inside this host.
2014-05-26 01:52:57 +00:00
2015-03-27 04:08:17 +00:00
![Windows Architecture Diagram ](/installation/images/win_docker_host.svg )
2015-07-12 14:09:14 +00:00
In Windows, the Docker host address is the address of the Linux VM. When you
start the VM with `docker-machine` it is assigned an IP address. When you start
a container, the ports on a container map to ports on the VM. To see this in
practice, work through the exercises on this page.
### Installation
If you have VirtualBox running, you must shut it down before running the
installer.
1. Go to the [Docker Toolbox ](https://www.docker.com/toolbox ) page.
2. Click the installer link to download.
3. Install Docker Toolbox by double-clicking the installer.
2014-06-08 20:11:50 +00:00
2015-07-12 14:09:14 +00:00
The installer launches the "Setup - Docker Toolbox" dialog.
![Install Docker Toolbox ](/installation/images/win-welcome.png )
2014-04-16 00:53:12 +00:00
2015-07-12 14:09:14 +00:00
4. Press "Next" to install the toolbox.
2014-04-16 00:53:12 +00:00
2015-07-12 14:09:14 +00:00
The installer presents you with options to customize the standard
installation. By default, the standard Docker Toolbox installation:
* installs executables for the Docker tools in `C:\Program Files\Docker Toolbox`
2015-08-22 05:06:11 +00:00
* install VirtualBox; or updates any existing installation
2015-07-12 14:09:14 +00:00
* adds a Docker Inc. folder to your program shortcuts
* updates your `PATH` environment variable
* adds desktop icons for the Docker Quickstart Terminal and Kitematic
2014-06-08 22:53:20 +00:00
2015-07-12 14:09:14 +00:00
This installation assumes the defaults are acceptable.
2014-04-16 00:53:12 +00:00
2015-07-12 14:09:14 +00:00
5. Press "Next" until you reach the "Ready to Install" page.
2014-04-16 00:53:12 +00:00
2015-07-12 14:09:14 +00:00
The system prompts you for your password.
![Install ](/installation/images/win-page-6.png )
6. Press "Install" to continue with the installation.
2014-04-16 00:53:12 +00:00
2015-07-12 14:09:14 +00:00
When it completes, the installer provides you with some information you can
use to complete some common tasks.
![All finished ](/installation/images/windows-finish.png )
2015-08-22 05:06:11 +00:00
7. Press "Finish" to exit.
2014-06-08 22:53:20 +00:00
2015-07-12 14:09:14 +00:00
## Running a Docker Container
2014-06-08 22:53:20 +00:00
2015-07-12 14:09:14 +00:00
To run a Docker container, you:
* create a new (or start an existing) Docker virtual machine
* switch your environment to your new VM
* use the `docker` client to create, load, and manage containers
Once you create a machine, you can reuse it as often as you like. Like any
VirtualBox VM, it maintains its configuration between uses.
There are several ways to use the installed tools, from the Docker Quickstart Terminal or
[from your shell ](#from-your-shell ).
2015-08-22 05:06:11 +00:00
### Using the Docker Quickstart Terminal
2015-07-12 14:09:14 +00:00
1. Find the Docker Quickstart Terminal icon on your Desktop and double-click to launch it.
The application:
* opens a terminal window
2015-08-22 05:06:11 +00:00
* creates a `default` VM if it doesn't exist, and starts the VM after
2015-07-12 14:09:14 +00:00
* points the terminal environment to this VM
Once the launch completes, you can run `docker` commands.
3. Verify your setup succeeded by running the `hello-world` container.
$ docker run hello-world
Unable to find image 'hello-world:latest' locally
511136ea3c5a: Pull complete
31cbccb51277: Pull complete
e45a5af57b00: Pull complete
hello-world:latest: The image you are pulling has been verified.
Important: image verification is a tech preview feature and should not be
relied on to provide security.
Status: Downloaded newer image for hello-world:latest
Hello from Docker.
This message shows that your installation appears to be working correctly.
To generate this message, Docker took the following steps:
1. The Docker client contacted the Docker daemon.
2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
(Assuming it was not already locally available.)
3. The Docker daemon created a new container from that image which runs the
executable that produces the output you are currently reading.
4. The Docker daemon streamed that output to the Docker client, which sent it
to your terminal.
To try something more ambitious, you can run an Ubuntu container with:
$ docker run -it ubuntu bash
For more examples and ideas, visit:
http://docs.docker.com/userguide/
2014-04-16 00:53:12 +00:00
2015-08-22 05:06:11 +00:00
### Using Docker from Windows Command Prompt (cmd.exe)
2014-12-29 08:19:42 +00:00
2015-08-22 05:06:11 +00:00
1. Launch a Windows Command Prompt (cmd.exe).
2015-07-12 14:09:14 +00:00
The `docker-machine` command requires `ssh.exe` in your `PATH` environment
variable. This `.exe` is in the MsysGit `bin` folder.
2. Add this to the `%PATH%` environment variable by running:
set PATH=%PATH%;"c:\Program Files (x86)\Git\bin"
3. Create a new Docker VM.
2015-08-10 20:29:08 +00:00
docker-machine create --driver virtualbox my-default
2015-07-12 14:09:14 +00:00
Creating VirtualBox VM...
Creating SSH key...
Starting VirtualBox VM...
Starting VM...
2015-08-10 20:29:08 +00:00
To see how to connect Docker to this machine, run: docker-machine env my-default
2015-07-12 14:09:14 +00:00
The command also creates a machine configuration in the
`C:\USERS\USERNAME\.docker\machine\machines` directory. You only need to run the `create`
command once. Then, you can use `docker-machine` to start, stop, query, and
otherwise manage the VM from the command line.
4. List your available machines.
2014-04-16 00:53:12 +00:00
2015-07-12 14:09:14 +00:00
C:\Users\mary> docker-machine ls
NAME ACTIVE DRIVER STATE URL SWARM
2015-08-10 20:29:08 +00:00
my-default * virtualbox Running tcp://192.168.99.101:2376
2015-07-12 14:09:14 +00:00
If you have previously installed the deprecated Boot2Docker application or
run the Docker Quickstart Terminal, you may have a `dev` VM as well.
2014-04-16 00:53:12 +00:00
2015-07-12 14:09:14 +00:00
5. Get the environment commands for your new VM.
2014-04-16 00:53:12 +00:00
2015-08-10 20:29:08 +00:00
C:\Users\mary> docker-machine env --shell cmd my-default
2015-07-12 14:09:14 +00:00
2015-08-10 20:29:08 +00:00
6. Connect your shell to the `my-default` machine.
2014-04-16 00:53:12 +00:00
2015-08-10 20:29:08 +00:00
C:\Users\mary> eval "$(docker-machine env my-default)"
2015-07-12 14:09:14 +00:00
7. Run the `hello-world` container to verify your setup.
C:\Users\mary> docker run hello-world
2014-12-05 20:08:23 +00:00
2015-08-22 05:06:11 +00:00
### Using Docker from PowerShell
2014-12-05 20:08:23 +00:00
2015-07-12 14:09:14 +00:00
1. Launch a Windows PowerShell window.
2. Add `ssh.exe` to your PATH:
PS C:\Users\mary> $Env:Path = "${Env:Path};c:\Program Files (x86)\Git\bin"
3. Create a new Docker VM.
2015-08-10 20:29:08 +00:00
PS C:\Users\mary> docker-machine create --driver virtualbox my-default
2015-07-12 14:09:14 +00:00
4. List your available machines.
C:\Users\mary> docker-machine ls
NAME ACTIVE DRIVER STATE URL SWARM
2015-08-10 20:29:08 +00:00
my-default * virtualbox Running tcp://192.168.99.101:2376
2015-07-12 14:09:14 +00:00
5. Get the environment commands for your new VM.
2014-12-19 06:43:34 +00:00
2015-08-10 20:29:08 +00:00
C:\Users\mary> docker-machine env --shell powershell my-default
2015-07-12 14:09:14 +00:00
2015-08-10 20:29:08 +00:00
6. Connect your shell to the `my-default` machine.
2014-12-19 06:43:34 +00:00
2015-08-10 20:29:08 +00:00
C:\Users\mary> eval "$(docker-machine env my-default)"
2015-03-27 21:54:37 +00:00
2015-07-12 14:09:14 +00:00
7. Run the `hello-world` container to verify your setup.
2015-03-27 21:54:37 +00:00
2015-07-12 14:09:14 +00:00
C:\Users\mary> docker run hello-world
2014-06-08 23:02:57 +00:00
2014-05-21 08:29:24 +00:00
2015-07-12 14:09:14 +00:00
## Learn about your Toolbox installation
2014-05-21 08:29:24 +00:00
2015-07-12 14:09:14 +00:00
Toolbox installs the Docker Engine binary in the `C:\Program Files\Docker
Toolbox` directory. When you use the Docker Quickstart Terminal or create a
2015-08-22 05:06:11 +00:00
`default` VM manually, Docker Machine updates the
2015-08-10 20:29:08 +00:00
`C:\USERS\USERNAME\.docker\machine\machines\default` folder to your
2015-07-12 14:09:14 +00:00
system. This folder contains the configuration for the VM.
2015-03-27 21:54:37 +00:00
2015-08-22 05:06:11 +00:00
You can create multiple VMs on your system with Docker Machine. Therefore, you
may end up with multiple VM folders if you have created more than one VM. To
remove a VM, use the `docker-machine rm <machine-name>` command.
2015-08-10 20:29:08 +00:00
## Migrate from Boot2Docker
If you were using Boot2Docker previously, you have a pre-existing Docker
`boot2docker-vm` VM on your local system. To allow Docker Machine to manage
this older VM, you can migrate it.
1. Open a terminal or the Docker CLI on your system.
2. Type the following command.
$ docker-machine create -d virtualbox --virtualbox-import-boot2docker-vm boot2docker-vm docker-vm
3. Use the `docker-machine` command to interact with the migrated VM.
2015-07-12 14:09:14 +00:00
The `docker-machine` subcommands are slightly different than the `boot2docker`
subcommands. The table below lists the equivalent `docker-machine` subcommand
and what it does:
2014-05-21 08:29:24 +00:00
2015-07-12 14:09:14 +00:00
| `boot2docker` | `docker-machine` | `docker-machine` description |
|----------------|------------------|----------------------------------------------------------|
| init | create | Creates a new docker host. |
| up | start | Starts a stopped machine. |
| ssh | ssh | Runs a command or interactive ssh session on the machine.|
| save | - | Not applicable. |
| down | stop | Stops a running machine. |
| poweroff | stop | Stops a running machine. |
| reset | restart | Restarts a running machine. |
| config | inspect | Prints machine configuration details. |
| status | ls | Lists all machines and their status. |
| info | inspect | Displays a machine's details. |
| ip | ip | Displays the machine's ip address. |
| shellinit | env | Displays shell commands needed to configure your shell to interact with a machine |
| delete | rm | Removes a machine. |
| download | - | Not applicable. |
| upgrade | upgrade | Upgrades a machine's Docker client to the latest stable release. |
2015-03-27 21:54:37 +00:00
2015-07-12 14:09:14 +00:00
## Upgrade Docker Toolbox
2015-03-27 21:54:37 +00:00
2015-07-12 14:09:14 +00:00
To upgrade Docker Toolbox, download an re-run [the Docker Toolbox
installer](https://www.docker.com/toolbox).
2014-05-28 04:42:19 +00:00
2014-06-08 23:02:57 +00:00
## Container port redirection
2015-08-22 05:06:11 +00:00
If you are curious, the username for the Docker default VM is `docker` and the
2015-08-05 16:07:11 +00:00
password is `tcuser` . The latest version of `docker-machine` sets up a host only
network adaptor which provides access to the container's ports.
2014-06-13 22:38:45 +00:00
2015-08-05 16:07:11 +00:00
If you run a container with a published port:
2014-05-28 04:42:19 +00:00
2015-08-05 16:07:11 +00:00
$ docker run --rm -i -t -p 80:80 nginx
2014-05-28 04:42:19 +00:00
2015-08-05 16:07:11 +00:00
Then you should be able to access that nginx server using the IP address
reported to you using:
2014-05-28 04:42:19 +00:00
2015-08-05 16:07:11 +00:00
$ docker-machine ip
2014-05-28 04:42:19 +00:00
2015-08-05 16:07:11 +00:00
Typically, the IP is 192.168.59.103, but it could get changed by VirtualBox's
DHCP implementation.
2015-03-27 21:54:37 +00:00
## Login with PUTTY instead of using the CMD
2015-08-05 16:07:11 +00:00
Docker Machine generates and uses the public/private key pair in your
`%USERPROFILE%\.ssh` directory so to log in you need to use the private key from
this same directory. The private key needs to be converted into the format PuTTY
uses. You can do this with
2015-03-27 21:54:37 +00:00
[puttygen ](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html ):
2015-08-05 16:07:11 +00:00
1. Open `puttygen.exe` and load ("File"->"Load" menu) the private key from
2015-08-19 07:59:49 +00:00
%USERPROFILE%\.docker\machine\machines\<name_of_your_machine>
2015-08-05 16:07:11 +00:00
2. Click "Save Private Key".
3. Use the saved file to login with PuTTY using `docker@127.0.0.1:2022` .
2015-04-02 21:57:39 +00:00
2015-04-29 19:51:57 +00:00
## Uninstallation
2015-07-12 14:09:14 +00:00
You can uninstall Docker Toolbox using Window's standard process for removing
programs. This process does not remove the `docker-install.exe` file. You must
delete that file yourself.
2015-04-29 19:51:57 +00:00
2015-07-12 14:09:14 +00:00
## Learn more
2015-04-02 21:57:39 +00:00
2015-07-12 14:09:14 +00:00
You can continue with the [Docker User Guide ](/userguide ). If you are
interested in using the Kitematic GUI, see the [Kitermatic user
guide](/kitematic/userguide/).