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