<commit_before>---
aliases:
- /engine/userguide/containers/dockerimages/
- /engine/userguide/dockerimages/
description: How to work with Docker images.
keywords:
- documentation, docs, the docker guide, docker guide, docker, docker platform, docker.io,
  Docker images, Docker image, image management, Docker repos, Docker repositories,
  docker, docker tag, docker tags, Docker Hub,  collaboration
menu:
  main:
    parent: engine_learn_menu
    weight: -4
title: Build your own images
---

# Build your own images

Docker images are the basis of containers. Each time you've used `docker run`
you told it which image you wanted. In the previous sections of the guide you
used Docker images that already exist, for example the `ubuntu` image and the
`training/webapp` image.

You also discovered that Docker stores downloaded images on the Docker host. If
an image isn't already present on the host then it'll be downloaded from a
registry: by default the [Docker Hub Registry](https://hub.docker.com).

In this section you're going to explore Docker images a bit more
including:

* Managing and working with images locally on your Docker host.
* Creating basic images.
* Uploading images to [Docker Hub Registry](https://hub.docker.com).

## Listing images on the host

Let's start with listing the images you have locally on our host. You can
do this using the `docker images` command like so:

    $ docker images

    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
    ubuntu              14.04               1d073211c498        3 days ago          187.9 MB
    busybox             latest              2c5ac3f849df        5 days ago          1.113 MB
    training/webapp     latest              54bb4e8718e8        5 months ago        348.7 MB

You can see the images you've previously used in the user guide.
Each has been downloaded from [Docker Hub](https://hub.docker.com) when you
launched a container using that image. When you list images, you get three crucial pieces of information in the listing.

* What repository they came from, for example `ubuntu`.
* The tags for each image, for example `14.04`.
* The image ID of each image.

> **Tip:**
> You can use [a third-party dockviz tool](https://github.com/justone/dockviz)
> or the [Image layers site](https://imagelayers.io/) to display  
> visualizations of image data.

A repository potentially holds multiple variants of an image. In the case of
our `ubuntu` image you can see multiple variants covering Ubuntu 10.04, 12.04,
12.10, 13.04, 13.10 and 14.04. Each variant is identified by a tag and you can
refer to a tagged image like so:

    ubuntu:14.04

So when you run a container you refer to a tagged image like so:

    $ docker run -t -i ubuntu:14.04 /bin/bash

If instead you wanted to run an Ubuntu 12.04 image you'd use:

    $ docker run -t -i ubuntu:12.04 /bin/bash

If you don't specify a variant, for example you just use `ubuntu`, then Docker
will default to using the `ubuntu:latest` image.

> **Tip:**
> You should always specify an image tag, for example `ubuntu:14.04`.
> That way, you always know exactly what variant of an image you are using.
> This is useful for troubleshooting and debugging.

## Getting a new image

So how do you get new images? Well Docker will automatically download any image
you use that isn't already present on the Docker host. But this can potentially
add some time to the launch of a container. If you want to pre-load an image you
can download it using the `docker pull` command. Suppose you'd like to
download the `centos` image.

    $ docker pull centos

    Using default tag: latest
    latest: Pulling from library/centos
    f1b10cd84249: Pull complete
    c852f6d61e65: Pull complete
    7322fbe74aa5: Pull complete
    Digest: sha256:90305c9112250c7e3746425477f1c4ef112b03b4abe78c612e092037bfecc3b7
    Status: Downloaded newer image for centos:latest

You can see that each layer of the image has been pulled down and now you
can run a container from this image and you won't have to wait to
download the image.

    $ docker run -t -i centos /bin/bash

    bash-4.1#

## Finding images

One of the features of Docker is that a lot of people have created Docker
images for a variety of purposes. Many of these have been uploaded to
[Docker Hub](https://hub.docker.com). You can search these images on the
[Docker Hub](https://hub.docker.com) website.

![indexsearch](search.png)

You can also search for images on the command line using the `docker search`
command. Suppose your team wants an image with Ruby and Sinatra installed on
which to do our web application development. You can search for a suitable image
by using the `docker search` command to find all the images that contain the
term `sinatra`.

    $ docker search sinatra
    NAME                                   DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
    training/sinatra                       Sinatra training image                          0                    [OK]
    marceldegraaf/sinatra                  Sinatra test app                                0
    mattwarren/docker-sinatra-demo                                                         0                    [OK]
    luisbebop/docker-sinatra-hello-world                                                   0                    [OK]
    bmorearty/handson-sinatra              handson-ruby + Sinatra for Hands on with D...   0
    subwiz/sinatra                                                                         0
    bmorearty/sinatra                                                                      0
    . . .

You can see the command returns a lot of images that use the term `sinatra`.
You've received a list of image names, descriptions, Stars (which measure the
social popularity of images - if a user likes an image then they can "star" it),
and the Official and Automated build statuses. [Official
Repositories](https://docs.docker.com/docker-hub/official_repos) are a carefully
curated set of Docker repositories supported by Docker, Inc.  Automated
repositories are [Automated Builds](dockerrepos.md#automated-builds) that allow
you to validate the source and content of an image.

You've reviewed the images available to use and you decided to use the
`training/sinatra` image. So far you've seen two types of images repositories,
images like `ubuntu`, which are called base or root images. These base images
are provided by Docker Inc and are built, validated and supported. These can be
identified by their single word names.

You've also seen user images, for example the `training/sinatra` image you've
chosen. A user image belongs to a member of the Docker community and is built
and maintained by them.  You can identify user images as they are always
prefixed with the user name, here `training`, of the user that created them.

## Pulling our image

You've identified a suitable image, `training/sinatra`, and now you can download it using the `docker pull` command.

    $ docker pull training/sinatra

The team can now use this image by running their own containers.

    $ docker run -t -i training/sinatra /bin/bash

    root@a8cb6ce02d85:/#

## Creating our own images

The team has found the `training/sinatra` image pretty useful but it's not quite
what they need and you need to make some changes to it. There are two ways you
can update and create images.

1. You can update a container created from an image and commit the results to an image.
2. You can use a `Dockerfile` to specify instructions to create an image.


### Updating and committing an image

To update an image you first need to create a container from the image
you'd like to update.

    $ docker run -t -i training/sinatra /bin/bash

    root@0b2616b0e5a8:/#

> **Note:**
> Take note of the container ID that has been created, `0b2616b0e5a8`, as you'll
> need it in a moment.

Inside our running container first let's update Ruby:

    root@0b2616b0e5a8:/# apt-get install -y ruby2.0-dev

Now let's add the `json` gem.

    root@0b2616b0e5a8:/# gem2.0 install json

Once this has completed let's exit our container using the `exit`
command.

Now you have a container with the change you want to make. You can then
commit a copy of this container to an image using the `docker commit`
command.

    $ docker commit -m "Added json gem" -a "<NAME>" \
    0b2616b0e5a8 ouruser/sinatra:v2

    4f177bd27a9ff0f6dc2a830403925b5360bfe0b93d476f7fc3231110e7f71b1c

Here you've used the `docker commit` command. You've specified two flags: `-m`
and `-a`. The `-m` flag allows us to specify a commit message, much like you
would with a commit on a version control system. The `-a` flag allows us to
specify an author for our update.

You've also specified the container you want to create this new image from,
`0b2616b0e5a8` (the ID you recorded earlier) and you've specified a target for
the image:<commit_msg>dockerimages.md: fix "gem2.0: command not found"<commit_after>---
aliases:
- /engine/userguide/containers/dockerimages/
- /engine/userguide/dockerimages/
description: How to work with Docker images.
keywords:
- documentation, docs, the docker guide, docker guide, docker, docker platform, docker.io,
  Docker images, Docker image, image management, Docker repos, Docker repositories,
  docker, docker tag, docker tags, Docker Hub,  collaboration
menu:
  main:
    parent: engine_learn_menu
    weight: -4
title: Build your own images
---

# Build your own images

Docker images are the basis of containers. Each time you've used `docker run`
you told it which image you wanted. In the previous sections of the guide you
used Docker images that already exist, for example the `ubuntu` image and the
`training/webapp` image.

You also discovered that Docker stores downloaded images on the Docker host. If
an image isn't already present on the host then it'll be downloaded from a
registry: by default the [Docker Hub Registry](https://hub.docker.com).

In this section you're going to explore Docker images a bit more
including:

* Managing and working with images locally on your Docker host.
* Creating basic images.
* Uploading images to [Docker Hub Registry](https://hub.docker.com).

## Listing images on the host

Let's start with listing the images you have locally on our host. You can
do this using the `docker images` command like so:

    $ docker images

    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
    ubuntu              14.04               1d073211c498        3 days ago          187.9 MB
    busybox             latest              2c5ac3f849df        5 days ago          1.113 MB
    training/webapp     latest              54bb4e8718e8        5 months ago        348.7 MB

You can see the images you've previously used in the user guide.
Each has been downloaded from [Docker Hub](https://hub.docker.com) when you
launched a container using that image. When you list images, you get three crucial pieces of information in the listing.

* What repository they came from, for example `ubuntu`.
* The tags for each image, for example `14.04`.
* The image ID of each image.

> **Tip:**
> You can use [a third-party dockviz tool](https://github.com/justone/dockviz)
> or the [Image layers site](https://imagelayers.io/) to display  
> visualizations of image data.

A repository potentially holds multiple variants of an image. In the case of
our `ubuntu` image you can see multiple variants covering Ubuntu 10.04, 12.04,
12.10, 13.04, 13.10 and 14.04. Each variant is identified by a tag and you can
refer to a tagged image like so:

    ubuntu:14.04

So when you run a container you refer to a tagged image like so:

    $ docker run -t -i ubuntu:14.04 /bin/bash

If instead you wanted to run an Ubuntu 12.04 image you'd use:

    $ docker run -t -i ubuntu:12.04 /bin/bash

If you don't specify a variant, for example you just use `ubuntu`, then Docker
will default to using the `ubuntu:latest` image.

> **Tip:**
> You should always specify an image tag, for example `ubuntu:14.04`.
> That way, you always know exactly what variant of an image you are using.
> This is useful for troubleshooting and debugging.

## Getting a new image

So how do you get new images? Well Docker will automatically download any image
you use that isn't already present on the Docker host. But this can potentially
add some time to the launch of a container. If you want to pre-load an image you
can download it using the `docker pull` command. Suppose you'd like to
download the `centos` image.

    $ docker pull centos

    Using default tag: latest
    latest: Pulling from library/centos
    f1b10cd84249: Pull complete
    c852f6d61e65: Pull complete
    7322fbe74aa5: Pull complete
    Digest: sha256:90305c9112250c7e3746425477f1c4ef112b03b4abe78c612e092037bfecc3b7
    Status: Downloaded newer image for centos:latest

You can see that each layer of the image has been pulled down and now you
can run a container from this image and you won't have to wait to
download the image.

    $ docker run -t -i centos /bin/bash

    bash-4.1#

## Finding images

One of the features of Docker is that a lot of people have created Docker
images for a variety of purposes. Many of these have been uploaded to
[Docker Hub](https://hub.docker.com). You can search these images on the
[Docker Hub](https://hub.docker.com) website.

![indexsearch](search.png)

You can also search for images on the command line using the `docker search`
command. Suppose your team wants an image with Ruby and Sinatra installed on
which to do our web application development. You can search for a suitable image
by using the `docker search` command to find all the images that contain the
term `sinatra`.

    $ docker search sinatra
    NAME                                   DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
    training/sinatra                       Sinatra training image                          0                    [OK]
    marceldegraaf/sinatra                  Sinatra test app                                0
    mattwarren/docker-sinatra-demo                                                         0                    [OK]
    luisbebop/docker-sinatra-hello-world                                                   0                    [OK]
    bmorearty/handson-sinatra              handson-ruby + Sinatra for Hands on with D...   0
    subwiz/sinatra                                                                         0
    bmorearty/sinatra                                                                      0
    . . .

You can see the command returns a lot of images that use the term `sinatra`.
You've received a list of image names, descriptions, Stars (which measure the
social popularity of images - if a user likes an image then they can "star" it),
and the Official and Automated build statuses. [Official
Repositories](https://docs.docker.com/docker-hub/official_repos) are a carefully
curated set of Docker repositories supported by Docker, Inc.  Automated
repositories are [Automated Builds](dockerrepos.md#automated-builds) that allow
you to validate the source and content of an image.

You've reviewed the images available to use and you decided to use the
`training/sinatra` image. So far you've seen two types of images repositories,
images like `ubuntu`, which are called base or root images. These base images
are provided by Docker Inc and are built, validated and supported. These can be
identified by their single word names.

You've also seen user images, for example the `training/sinatra` image you've
chosen. A user image belongs to a member of the Docker community and is built
and maintained by them.  You can identify user images as they are always
prefixed with the user name, here `training`, of the user that created them.

## Pulling our image

You've identified a suitable image, `training/sinatra`, and now you can download it using the `docker pull` command.

    $ docker pull training/sinatra

The team can now use this image by running their own containers.

    $ docker run -t -i training/sinatra /bin/bash

    root@a8cb6ce02d85:/#

## Creating our own images

The team has found the `training/sinatra` image pretty useful but it's not quite
what they need and you need to make some changes to it. There are two ways you
can update and create images.

1. You can update a container created from an image and commit the results to an image.
2. You can use a `Dockerfile` to specify instructions to create an image.


### Updating and committing an image

To update an image you first need to create a container from the image
you'd like to update.

    $ docker run -t -i training/sinatra /bin/bash

    root@0b2616b0e5a8:/#

> **Note:**
> Take note of the container ID that has been created, `0b2616b0e5a8`, as you'll
> need it in a moment.

Inside our running container first let's update Ruby:

    root@0b2616b0e5a8:/# apt-get install -y ruby2.0-dev ruby2.0

Now let's add the `json` gem.

    root@0b2616b0e5a8:/# gem2.0 install json

Once this has completed let's exit our container using the `exit`
command.

Now you have a container with the change you want to make. You can then
commit a copy of this container to an image using the `docker commit`
command.

    $ docker commit -m "Added json gem" -a "<NAME>" \
    0b2616b0e5a8 ouruser/sinatra:v2

    4f177bd27a9ff0f6dc2a830403925b5360bfe0b93d476f7fc3231110e7f71b1c

Here you've used the `docker commit` command. You've specified two flags: `-m`
and `-a`. The `-m` flag allows us to specify a commit message, much like you
would with a commit on a version control system. The `-a` flag allows us to
specify an author for our update.

You've also specified the container you want to create this new image from,
`0b2616b0e5a8` (the ID you recorded earlier) and you've specified a target for
the image:
{'fraction_non_alphanumeric': 0.05871201561193198, 'fraction_numerical': 0.03066629495400056, 'mean_word_length': 2.803223070398643, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 27, 'https://': 16, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 50, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6792995', 'n_tokens_mistral': 5368, 'n_tokens_neox': 4751, 'n_words': 2437}