github.com/jogo/docker@v1.7.0-rc1/docs/sources/userguide/dockerimages.md (about) 1 page_title: Working with Docker images 2 page_description: How to work with Docker images. 3 page_keywords: documentation, docs, the docker guide, docker guide, docker, docker platform, virtualization framework, docker.io, Docker images, Docker image, image management, Docker repos, Docker repositories, docker, docker tag, docker tags, Docker Hub, collaboration 4 5 # Working with Docker images 6 7 In the [introduction](/introduction/understanding-docker/) we've discovered that Docker 8 images are the basis of containers. In the 9 [previous](/userguide/dockerizing/) [sections](/userguide/usingdocker/) 10 we've used Docker images that already exist, for example the `ubuntu` 11 image and the `training/webapp` image. 12 13 We've also discovered that Docker stores downloaded images on the Docker 14 host. If an image isn't already present on the host then it'll be 15 downloaded from a registry: by default the 16 [Docker Hub Registry](https://registry.hub.docker.com). 17 18 In this section we're going to explore Docker images a bit more 19 including: 20 21 * Managing and working with images locally on your Docker host; 22 * Creating basic images; 23 * Uploading images to [Docker Hub Registry](https://registry.hub.docker.com). 24 25 ## Listing images on the host 26 27 Let's start with listing the images we have locally on our host. You can 28 do this using the `docker images` command like so: 29 30 $ docker images 31 REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 32 training/webapp latest fc77f57ad303 3 weeks ago 280.5 MB 33 ubuntu 13.10 5e019ab7bf6d 4 weeks ago 180 MB 34 ubuntu saucy 5e019ab7bf6d 4 weeks ago 180 MB 35 ubuntu 12.04 74fe38d11401 4 weeks ago 209.6 MB 36 ubuntu precise 74fe38d11401 4 weeks ago 209.6 MB 37 ubuntu 12.10 a7cf8ae4e998 4 weeks ago 171.3 MB 38 ubuntu quantal a7cf8ae4e998 4 weeks ago 171.3 MB 39 ubuntu 14.04 99ec81b80c55 4 weeks ago 266 MB 40 ubuntu latest 99ec81b80c55 4 weeks ago 266 MB 41 ubuntu trusty 99ec81b80c55 4 weeks ago 266 MB 42 ubuntu 13.04 316b678ddf48 4 weeks ago 169.4 MB 43 ubuntu raring 316b678ddf48 4 weeks ago 169.4 MB 44 ubuntu 10.04 3db9c44f4520 4 weeks ago 183 MB 45 ubuntu lucid 3db9c44f4520 4 weeks ago 183 MB 46 47 We can see the images we've previously used in our [user guide](/userguide/). 48 Each has been downloaded from [Docker Hub](https://hub.docker.com) when we 49 launched a container using that image. 50 51 We can see three crucial pieces of information about our images in the listing. 52 53 * What repository they came from, for example `ubuntu`. 54 * The tags for each image, for example `14.04`. 55 * The image ID of each image. 56 57 > **Note:** 58 > Previously, the `docker images` command supported the `--tree` and `--dot` 59 > arguments, which displayed different visualizations of the image data. Docker 60 > core removed this functionality in the 1.7 version. If you liked this 61 > functionality, you can still find it in 62 > [the third-party dockviz tool](https://github.com/justone/dockviz). 63 64 A repository potentially holds multiple variants of an image. In the case of 65 our `ubuntu` image we can see multiple variants covering Ubuntu 10.04, 12.04, 66 12.10, 13.04, 13.10 and 14.04. Each variant is identified by a tag and you can 67 refer to a tagged image like so: 68 69 ubuntu:14.04 70 71 So when we run a container we refer to a tagged image like so: 72 73 $ docker run -t -i ubuntu:14.04 /bin/bash 74 75 If instead we wanted to run an Ubuntu 12.04 image we'd use: 76 77 $ docker run -t -i ubuntu:12.04 /bin/bash 78 79 If you don't specify a variant, for example you just use `ubuntu`, then Docker 80 will default to using the `ubuntu:latest` image. 81 82 > **Tip:** 83 > We recommend you always use a specific tagged image, for example 84 > `ubuntu:12.04`. That way you always know exactly what variant of an image is 85 > being used. 86 87 ## Getting a new image 88 89 So how do we get new images? Well Docker will automatically download any image 90 we use that isn't already present on the Docker host. But this can potentially 91 add some time to the launch of a container. If we want to pre-load an image we 92 can download it using the `docker pull` command. Let's say we'd like to 93 download the `centos` image. 94 95 $ docker pull centos 96 Pulling repository centos 97 b7de3133ff98: Pulling dependent layers 98 5cc9e91966f7: Pulling fs layer 99 511136ea3c5a: Download complete 100 ef52fb1fe610: Download complete 101 . . . 102 103 Status: Downloaded newer image for centos 104 105 We can see that each layer of the image has been pulled down and now we 106 can run a container from this image and we won't have to wait to 107 download the image. 108 109 $ docker run -t -i centos /bin/bash 110 bash-4.1# 111 112 ## Finding images 113 114 One of the features of Docker is that a lot of people have created Docker 115 images for a variety of purposes. Many of these have been uploaded to 116 [Docker Hub](https://hub.docker.com). We can search these images on the 117 [Docker Hub](https://hub.docker.com) website. 118 119  120 121 We can also search for images on the command line using the `docker search` 122 command. Let's say our team wants an image with Ruby and Sinatra installed on 123 which to do our web application development. We can search for a suitable image 124 by using the `docker search` command to find all the images that contain the 125 term `sinatra`. 126 127 $ docker search sinatra 128 NAME DESCRIPTION STARS OFFICIAL AUTOMATED 129 training/sinatra Sinatra training image 0 [OK] 130 marceldegraaf/sinatra Sinatra test app 0 131 mattwarren/docker-sinatra-demo 0 [OK] 132 luisbebop/docker-sinatra-hello-world 0 [OK] 133 bmorearty/handson-sinatra handson-ruby + Sinatra for Hands on with D... 0 134 subwiz/sinatra 0 135 bmorearty/sinatra 0 136 . . . 137 138 We can see we've returned a lot of images that use the term `sinatra`. We've 139 returned a list of image names, descriptions, Stars (which measure the social 140 popularity of images - if a user likes an image then they can "star" it), and 141 the Official and Automated build statuses. 142 [Official Repositories](/docker-hub/official_repos) are a carefully curated set 143 of Docker repositories supported by Docker, Inc. Automated repositories are 144 [Automated Builds](/userguide/dockerrepos/#automated-builds) that allow you to 145 validate the source and content of an image. 146 147 We've reviewed the images available to use and we decided to use the 148 `training/sinatra` image. So far we've seen two types of images repositories, 149 images like `ubuntu`, which are called base or root images. These base images 150 are provided by Docker Inc and are built, validated and supported. These can be 151 identified by their single word names. 152 153 We've also seen user images, for example the `training/sinatra` image we've 154 chosen. A user image belongs to a member of the Docker community and is built 155 and maintained by them. You can identify user images as they are always 156 prefixed with the user name, here `training`, of the user that created them. 157 158 ## Pulling our image 159 160 We've identified a suitable image, `training/sinatra`, and now we can download it using the `docker pull` command. 161 162 $ docker pull training/sinatra 163 164 The team can now use this image by running their own containers. 165 166 $ docker run -t -i training/sinatra /bin/bash 167 root@a8cb6ce02d85:/# 168 169 ## Creating our own images 170 171 The team has found the `training/sinatra` image pretty useful but it's not quite what 172 they need and we need to make some changes to it. There are two ways we can 173 update and create images. 174 175 1. We can update a container created from an image and commit the results to an image. 176 2. We can use a `Dockerfile` to specify instructions to create an image. 177 178 179 ### Updating and committing an image 180 181 To update an image we first need to create a container from the image 182 we'd like to update. 183 184 $ docker run -t -i training/sinatra /bin/bash 185 root@0b2616b0e5a8:/# 186 187 > **Note:** 188 > Take note of the container ID that has been created, `0b2616b0e5a8`, as we'll 189 > need it in a moment. 190 191 Inside our running container let's add the `json` gem. 192 193 root@0b2616b0e5a8:/# gem install json 194 195 Once this has completed let's exit our container using the `exit` 196 command. 197 198 Now we have a container with the change we want to make. We can then 199 commit a copy of this container to an image using the `docker commit` 200 command. 201 202 $ docker commit -m "Added json gem" -a "Kate Smith" \ 203 0b2616b0e5a8 ouruser/sinatra:v2 204 4f177bd27a9ff0f6dc2a830403925b5360bfe0b93d476f7fc3231110e7f71b1c 205 206 Here we've used the `docker commit` command. We've specified two flags: `-m` 207 and `-a`. The `-m` flag allows us to specify a commit message, much like you 208 would with a commit on a version control system. The `-a` flag allows us to 209 specify an author for our update. 210 211 We've also specified the container we want to create this new image from, 212 `0b2616b0e5a8` (the ID we recorded earlier) and we've specified a target for 213 the image: 214 215 ouruser/sinatra:v2 216 217 Let's break this target down. It consists of a new user, `ouruser`, that we're 218 writing this image to. We've also specified the name of the image, here we're 219 keeping the original image name `sinatra`. Finally we're specifying a tag for 220 the image: `v2`. 221 222 We can then look at our new `ouruser/sinatra` image using the `docker images` 223 command. 224 225 $ docker images 226 REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 227 training/sinatra latest 5bc342fa0b91 10 hours ago 446.7 MB 228 ouruser/sinatra v2 3c59e02ddd1a 10 hours ago 446.7 MB 229 ouruser/sinatra latest 5db5f8471261 10 hours ago 446.7 MB 230 231 To use our new image to create a container we can then: 232 233 $ docker run -t -i ouruser/sinatra:v2 /bin/bash 234 root@78e82f680994:/# 235 236 ### Building an image from a `Dockerfile` 237 238 Using the `docker commit` command is a pretty simple way of extending an image 239 but it's a bit cumbersome and it's not easy to share a development process for 240 images amongst a team. Instead we can use a new command, `docker build`, to 241 build new images from scratch. 242 243 To do this we create a `Dockerfile` that contains a set of instructions that 244 tell Docker how to build our image. 245 246 Let's create a directory and a `Dockerfile` first. 247 248 $ mkdir sinatra 249 $ cd sinatra 250 $ touch Dockerfile 251 252 If you are using Boot2Docker on Windows, you may access your host 253 directory by `cd` to `/c/Users/your_user_name`. 254 255 Each instruction creates a new layer of the image. Let's look at a simple 256 example now for building our own Sinatra image for our development team. 257 258 # This is a comment 259 FROM ubuntu:14.04 260 MAINTAINER Kate Smith <ksmith@example.com> 261 RUN apt-get update && apt-get install -y ruby ruby-dev 262 RUN gem install sinatra 263 264 Let's look at what our `Dockerfile` does. Each instruction prefixes a statement and is capitalized. 265 266 INSTRUCTION statement 267 268 > **Note:** 269 > We use `#` to indicate a comment 270 271 The first instruction `FROM` tells Docker what the source of our image is, in 272 this case we're basing our new image on an Ubuntu 14.04 image. 273 274 Next we use the `MAINTAINER` instruction to specify who maintains our new image. 275 276 Lastly, we've specified two `RUN` instructions. A `RUN` instruction executes 277 a command inside the image, for example installing a package. Here we're 278 updating our APT cache, installing Ruby and RubyGems and then installing the 279 Sinatra gem. 280 281 > **Note:** 282 > There are [a lot more instructions available to us in a Dockerfile](/reference/builder). 283 284 Now let's take our `Dockerfile` and use the `docker build` command to build an image. 285 286 $ docker build -t ouruser/sinatra:v2 . 287 Sending build context to Docker daemon 2.048 kB 288 Sending build context to Docker daemon 289 Step 0 : FROM ubuntu:14.04 290 ---> e54ca5efa2e9 291 Step 1 : MAINTAINER Kate Smith <ksmith@example.com> 292 ---> Using cache 293 ---> 851baf55332b 294 Step 2 : RUN apt-get update && apt-get install -y ruby ruby-dev 295 ---> Running in 3a2558904e9b 296 Selecting previously unselected package libasan0:amd64. 297 (Reading database ... 11518 files and directories currently installed.) 298 Preparing to unpack .../libasan0_4.8.2-19ubuntu1_amd64.deb ... 299 Unpacking libasan0:amd64 (4.8.2-19ubuntu1) ... 300 Selecting previously unselected package libatomic1:amd64. 301 Preparing to unpack .../libatomic1_4.8.2-19ubuntu1_amd64.deb ... 302 Unpacking libatomic1:amd64 (4.8.2-19ubuntu1) ... 303 Selecting previously unselected package libgmp10:amd64. 304 Preparing to unpack .../libgmp10_2%3a5.1.3+dfsg-1ubuntu1_amd64.deb ... 305 Unpacking libgmp10:amd64 (2:5.1.3+dfsg-1ubuntu1) ... 306 Selecting previously unselected package libisl10:amd64. 307 Preparing to unpack .../libisl10_0.12.2-1_amd64.deb ... 308 Unpacking libisl10:amd64 (0.12.2-1) ... 309 Selecting previously unselected package libcloog-isl4:amd64. 310 Preparing to unpack .../libcloog-isl4_0.18.2-1_amd64.deb ... 311 Unpacking libcloog-isl4:amd64 (0.18.2-1) ... 312 Selecting previously unselected package libgomp1:amd64. 313 Preparing to unpack .../libgomp1_4.8.2-19ubuntu1_amd64.deb ... 314 Unpacking libgomp1:amd64 (4.8.2-19ubuntu1) ... 315 Selecting previously unselected package libitm1:amd64. 316 Preparing to unpack .../libitm1_4.8.2-19ubuntu1_amd64.deb ... 317 Unpacking libitm1:amd64 (4.8.2-19ubuntu1) ... 318 Selecting previously unselected package libmpfr4:amd64. 319 Preparing to unpack .../libmpfr4_3.1.2-1_amd64.deb ... 320 Unpacking libmpfr4:amd64 (3.1.2-1) ... 321 Selecting previously unselected package libquadmath0:amd64. 322 Preparing to unpack .../libquadmath0_4.8.2-19ubuntu1_amd64.deb ... 323 Unpacking libquadmath0:amd64 (4.8.2-19ubuntu1) ... 324 Selecting previously unselected package libtsan0:amd64. 325 Preparing to unpack .../libtsan0_4.8.2-19ubuntu1_amd64.deb ... 326 Unpacking libtsan0:amd64 (4.8.2-19ubuntu1) ... 327 Selecting previously unselected package libyaml-0-2:amd64. 328 Preparing to unpack .../libyaml-0-2_0.1.4-3ubuntu3_amd64.deb ... 329 Unpacking libyaml-0-2:amd64 (0.1.4-3ubuntu3) ... 330 Selecting previously unselected package libmpc3:amd64. 331 Preparing to unpack .../libmpc3_1.0.1-1ubuntu1_amd64.deb ... 332 Unpacking libmpc3:amd64 (1.0.1-1ubuntu1) ... 333 Selecting previously unselected package openssl. 334 Preparing to unpack .../openssl_1.0.1f-1ubuntu2.4_amd64.deb ... 335 Unpacking openssl (1.0.1f-1ubuntu2.4) ... 336 Selecting previously unselected package ca-certificates. 337 Preparing to unpack .../ca-certificates_20130906ubuntu2_all.deb ... 338 Unpacking ca-certificates (20130906ubuntu2) ... 339 Selecting previously unselected package manpages. 340 Preparing to unpack .../manpages_3.54-1ubuntu1_all.deb ... 341 Unpacking manpages (3.54-1ubuntu1) ... 342 Selecting previously unselected package binutils. 343 Preparing to unpack .../binutils_2.24-5ubuntu3_amd64.deb ... 344 Unpacking binutils (2.24-5ubuntu3) ... 345 Selecting previously unselected package cpp-4.8. 346 Preparing to unpack .../cpp-4.8_4.8.2-19ubuntu1_amd64.deb ... 347 Unpacking cpp-4.8 (4.8.2-19ubuntu1) ... 348 Selecting previously unselected package cpp. 349 Preparing to unpack .../cpp_4%3a4.8.2-1ubuntu6_amd64.deb ... 350 Unpacking cpp (4:4.8.2-1ubuntu6) ... 351 Selecting previously unselected package libgcc-4.8-dev:amd64. 352 Preparing to unpack .../libgcc-4.8-dev_4.8.2-19ubuntu1_amd64.deb ... 353 Unpacking libgcc-4.8-dev:amd64 (4.8.2-19ubuntu1) ... 354 Selecting previously unselected package gcc-4.8. 355 Preparing to unpack .../gcc-4.8_4.8.2-19ubuntu1_amd64.deb ... 356 Unpacking gcc-4.8 (4.8.2-19ubuntu1) ... 357 Selecting previously unselected package gcc. 358 Preparing to unpack .../gcc_4%3a4.8.2-1ubuntu6_amd64.deb ... 359 Unpacking gcc (4:4.8.2-1ubuntu6) ... 360 Selecting previously unselected package libc-dev-bin. 361 Preparing to unpack .../libc-dev-bin_2.19-0ubuntu6_amd64.deb ... 362 Unpacking libc-dev-bin (2.19-0ubuntu6) ... 363 Selecting previously unselected package linux-libc-dev:amd64. 364 Preparing to unpack .../linux-libc-dev_3.13.0-30.55_amd64.deb ... 365 Unpacking linux-libc-dev:amd64 (3.13.0-30.55) ... 366 Selecting previously unselected package libc6-dev:amd64. 367 Preparing to unpack .../libc6-dev_2.19-0ubuntu6_amd64.deb ... 368 Unpacking libc6-dev:amd64 (2.19-0ubuntu6) ... 369 Selecting previously unselected package ruby. 370 Preparing to unpack .../ruby_1%3a1.9.3.4_all.deb ... 371 Unpacking ruby (1:1.9.3.4) ... 372 Selecting previously unselected package ruby1.9.1. 373 Preparing to unpack .../ruby1.9.1_1.9.3.484-2ubuntu1_amd64.deb ... 374 Unpacking ruby1.9.1 (1.9.3.484-2ubuntu1) ... 375 Selecting previously unselected package libruby1.9.1. 376 Preparing to unpack .../libruby1.9.1_1.9.3.484-2ubuntu1_amd64.deb ... 377 Unpacking libruby1.9.1 (1.9.3.484-2ubuntu1) ... 378 Selecting previously unselected package manpages-dev. 379 Preparing to unpack .../manpages-dev_3.54-1ubuntu1_all.deb ... 380 Unpacking manpages-dev (3.54-1ubuntu1) ... 381 Selecting previously unselected package ruby1.9.1-dev. 382 Preparing to unpack .../ruby1.9.1-dev_1.9.3.484-2ubuntu1_amd64.deb ... 383 Unpacking ruby1.9.1-dev (1.9.3.484-2ubuntu1) ... 384 Selecting previously unselected package ruby-dev. 385 Preparing to unpack .../ruby-dev_1%3a1.9.3.4_all.deb ... 386 Unpacking ruby-dev (1:1.9.3.4) ... 387 Setting up libasan0:amd64 (4.8.2-19ubuntu1) ... 388 Setting up libatomic1:amd64 (4.8.2-19ubuntu1) ... 389 Setting up libgmp10:amd64 (2:5.1.3+dfsg-1ubuntu1) ... 390 Setting up libisl10:amd64 (0.12.2-1) ... 391 Setting up libcloog-isl4:amd64 (0.18.2-1) ... 392 Setting up libgomp1:amd64 (4.8.2-19ubuntu1) ... 393 Setting up libitm1:amd64 (4.8.2-19ubuntu1) ... 394 Setting up libmpfr4:amd64 (3.1.2-1) ... 395 Setting up libquadmath0:amd64 (4.8.2-19ubuntu1) ... 396 Setting up libtsan0:amd64 (4.8.2-19ubuntu1) ... 397 Setting up libyaml-0-2:amd64 (0.1.4-3ubuntu3) ... 398 Setting up libmpc3:amd64 (1.0.1-1ubuntu1) ... 399 Setting up openssl (1.0.1f-1ubuntu2.4) ... 400 Setting up ca-certificates (20130906ubuntu2) ... 401 debconf: unable to initialize frontend: Dialog 402 debconf: (TERM is not set, so the dialog frontend is not usable.) 403 debconf: falling back to frontend: Readline 404 debconf: unable to initialize frontend: Readline 405 debconf: (This frontend requires a controlling tty.) 406 debconf: falling back to frontend: Teletype 407 Setting up manpages (3.54-1ubuntu1) ... 408 Setting up binutils (2.24-5ubuntu3) ... 409 Setting up cpp-4.8 (4.8.2-19ubuntu1) ... 410 Setting up cpp (4:4.8.2-1ubuntu6) ... 411 Setting up libgcc-4.8-dev:amd64 (4.8.2-19ubuntu1) ... 412 Setting up gcc-4.8 (4.8.2-19ubuntu1) ... 413 Setting up gcc (4:4.8.2-1ubuntu6) ... 414 Setting up libc-dev-bin (2.19-0ubuntu6) ... 415 Setting up linux-libc-dev:amd64 (3.13.0-30.55) ... 416 Setting up libc6-dev:amd64 (2.19-0ubuntu6) ... 417 Setting up manpages-dev (3.54-1ubuntu1) ... 418 Setting up libruby1.9.1 (1.9.3.484-2ubuntu1) ... 419 Setting up ruby1.9.1-dev (1.9.3.484-2ubuntu1) ... 420 Setting up ruby-dev (1:1.9.3.4) ... 421 Setting up ruby (1:1.9.3.4) ... 422 Setting up ruby1.9.1 (1.9.3.484-2ubuntu1) ... 423 Processing triggers for libc-bin (2.19-0ubuntu6) ... 424 Processing triggers for ca-certificates (20130906ubuntu2) ... 425 Updating certificates in /etc/ssl/certs... 164 added, 0 removed; done. 426 Running hooks in /etc/ca-certificates/update.d....done. 427 ---> c55c31703134 428 Removing intermediate container 3a2558904e9b 429 Step 3 : RUN gem install sinatra 430 ---> Running in 6b81cb6313e5 431 unable to convert "\xC3" to UTF-8 in conversion from ASCII-8BIT to UTF-8 to US-ASCII for README.rdoc, skipping 432 unable to convert "\xC3" to UTF-8 in conversion from ASCII-8BIT to UTF-8 to US-ASCII for README.rdoc, skipping 433 Successfully installed rack-1.5.2 434 Successfully installed tilt-1.4.1 435 Successfully installed rack-protection-1.5.3 436 Successfully installed sinatra-1.4.5 437 4 gems installed 438 Installing ri documentation for rack-1.5.2... 439 Installing ri documentation for tilt-1.4.1... 440 Installing ri documentation for rack-protection-1.5.3... 441 Installing ri documentation for sinatra-1.4.5... 442 Installing RDoc documentation for rack-1.5.2... 443 Installing RDoc documentation for tilt-1.4.1... 444 Installing RDoc documentation for rack-protection-1.5.3... 445 Installing RDoc documentation for sinatra-1.4.5... 446 ---> 97feabe5d2ed 447 Removing intermediate container 6b81cb6313e5 448 Successfully built 97feabe5d2ed 449 450 We've specified our `docker build` command and used the `-t` flag to identify 451 our new image as belonging to the user `ouruser`, the repository name `sinatra` 452 and given it the tag `v2`. 453 454 We've also specified the location of our `Dockerfile` using the `.` to 455 indicate a `Dockerfile` in the current directory. 456 457 > **Note:** 458 > You can also specify a path to a `Dockerfile`. 459 460 Now we can see the build process at work. The first thing Docker does is 461 upload the build context: basically the contents of the directory you're 462 building in. This is done because the Docker daemon does the actual 463 build of the image and it needs the local context to do it. 464 465 Next we can see each instruction in the `Dockerfile` being executed 466 step-by-step. We can see that each step creates a new container, runs 467 the instruction inside that container and then commits that change - 468 just like the `docker commit` work flow we saw earlier. When all the 469 instructions have executed we're left with the `97feabe5d2ed` image 470 (also helpfully tagged as `ouruser/sinatra:v2`) and all intermediate 471 containers will get removed to clean things up. 472 473 > **Note:** 474 > An image can't have more than 127 layers regardless of the storage driver. 475 > This limitation is set globally to encourage optimization of the overall 476 > size of images. 477 478 We can then create a container from our new image. 479 480 $ docker run -t -i ouruser/sinatra:v2 /bin/bash 481 root@8196968dac35:/# 482 483 > **Note:** 484 > This is just a brief introduction to creating images. We've 485 > skipped a whole bunch of other instructions that you can use. We'll see more of 486 > those instructions in later sections of the Guide or you can refer to the 487 > [`Dockerfile`](/reference/builder/) reference for a 488 > detailed description and examples of every instruction. 489 > To help you write a clear, readable, maintainable `Dockerfile`, we've also 490 > written a [`Dockerfile` Best Practices guide](/articles/dockerfile_best-practices). 491 492 ### More 493 494 To learn more, check out the [Dockerfile tutorial](/userguide/level1). 495 496 ## Setting tags on an image 497 498 You can also add a tag to an existing image after you commit or build it. We 499 can do this using the `docker tag` command. Let's add a new tag to our 500 `ouruser/sinatra` image. 501 502 $ docker tag 5db5f8471261 ouruser/sinatra:devel 503 504 The `docker tag` command takes the ID of the image, here `5db5f8471261`, and our 505 user name, the repository name and the new tag. 506 507 Let's see our new tag using the `docker images` command. 508 509 $ docker images ouruser/sinatra 510 REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 511 ouruser/sinatra latest 5db5f8471261 11 hours ago 446.7 MB 512 ouruser/sinatra devel 5db5f8471261 11 hours ago 446.7 MB 513 ouruser/sinatra v2 5db5f8471261 11 hours ago 446.7 MB 514 515 ## Image Digests 516 517 Images that use the v2 or later format have a content-addressable identifier 518 called a `digest`. As long as the input used to generate the image is 519 unchanged, the digest value is predictable. To list image digest values, use 520 the `--digests` flag: 521 522 $ docker images --digests | head 523 REPOSITORY TAG DIGEST IMAGE ID CREATED VIRTUAL SIZE 524 ouruser/sinatra latest sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 5db5f8471261 11 hours ago 446.7 MB 525 526 When pushing or pulling to a 2.0 registry, the `push` or `pull` command 527 output includes the image digest. You can `pull` using a digest value. 528 529 $ docker pull ouruser/sinatra@cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 530 531 You can also reference by digest in `create`, `run`, and `rmi` commands, as well as the 532 `FROM` image reference in a Dockerfile. 533 534 ## Push an image to Docker Hub 535 536 Once you've built or created a new image you can push it to [Docker 537 Hub](https://hub.docker.com) using the `docker push` command. This 538 allows you to share it with others, either publicly, or push it into [a 539 private repository](https://registry.hub.docker.com/plans/). 540 541 $ docker push ouruser/sinatra 542 The push refers to a repository [ouruser/sinatra] (len: 1) 543 Sending image list 544 Pushing repository ouruser/sinatra (3 tags) 545 . . . 546 547 ## Remove an image from the host 548 549 You can also remove images on your Docker host in a way [similar to 550 containers]( 551 /userguide/usingdocker) using the `docker rmi` command. 552 553 Let's delete the `training/sinatra` image as we don't need it anymore. 554 555 $ docker rmi training/sinatra 556 Untagged: training/sinatra:latest 557 Deleted: 5bc342fa0b91cabf65246837015197eecfa24b2213ed6a51a8974ae250fedd8d 558 Deleted: ed0fffdcdae5eb2c3a55549857a8be7fc8bc4241fb19ad714364cbfd7a56b22f 559 Deleted: 5c58979d73ae448df5af1d8142436d81116187a7633082650549c52c3a2418f0 560 561 > **Note:** In order to remove an image from the host, please make sure 562 > that there are no containers actively based on it. 563 564 # Next steps 565 566 Until now we've seen how to build individual applications inside Docker 567 containers. Now learn how to build whole application stacks with Docker 568 by linking together multiple Docker containers. 569 570 Test your Dockerfile knowledge with the 571 [Dockerfile tutorial](/userguide/level1). 572 573 Go to [Linking Containers Together](/userguide/dockerlinks). 574 575