How are docker image names parsed?

When doing a docker push or when pulling an image, how does Docker determine if there is a registry server in the image name or if it is a path/username on the default registry (e.g. Docker Hub)?

I’m seeing the following from the 1.1 image spec:

  • Running Docker compose with ElasticSearch on OS X gives me error sysctl: setting key “vm.max_map_count”: Read-only file system
  • How to connect two docker containers through localhost?
  • Docker: running application with a remote X-server
  • Why doesn't Linux seek the command in all the directories in PATH environment?
  • From local development to dockerized microservices
  • How many containers should exist per host in production? How should services be split?
  • Tag

    A tag serves to map a descriptive, user-given name to any single image
    ID. Tag values are limited to the set of characters [a-zA-Z_0-9].


    A collection of tags grouped under a common prefix (the name component
    before :). For example, in an image tagged with the name my-app:3.1.4,
    my-app is the Repository component of the name. A repository name is
    made up of slash-separated name components, optionally prefixed by a
    DNS hostname. The hostname must follow comply with standard DNS rules,
    but may not contain _ characters. If a hostname is present, it may
    optionally be followed by a port number in the format :8080. Name
    components may contain lowercase characters, digits, and separators. A
    separator is defined as a period, one or two underscores, or one or
    more dashes. A name component may not start or end with a separator.

    For the DNS host name, does it need to be fully qualified with dots, or is “my-local-server” a valid registry hostname? For the name components, I’m seeing periods as valid, which implies “team.user/appserver” is a valid image name. If the registry server is running on port 80, and therefore no port number is needed on the hostname in the image name, it seems like there would be ambiguity between the hostname and the path on the registry server. I’m curious how Docker resolves that ambiguity.

  • Gitlab migrate from 6.x to 8 in docker
  • Can't build docker image via gradle on Windows 10
  • Simpliest Dockerfile ever to untar: file not found
  • Docker - Unable to use placeholders inside ENTRYPOINT
  • How to specify IBM Containers' IP to register
  • Virtualbox inside Docker
  • One Solution collect form web for “How are docker image names parsed?”

    TL;DR: The hostname must contain a . dns separator or a : port separator before the first /, otherwise the code assumes you want the default registry.

    After some digging through the code, I came across distribution/reference/reference.go with the following:

    // Grammar
    //  reference                       := name [ ":" tag ] [ "@" digest ]
    //  name                            := [hostname '/'] component ['/' component]*
    //  hostname                        := hostcomponent ['.' hostcomponent]* [':' port-number]
    //  hostcomponent                   := /([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])/
    //  port-number                     := /[0-9]+/
    //  component                       := alpha-numeric [separator alpha-numeric]*
    //  alpha-numeric                   := /[a-z0-9]+/
    //  separator                       := /[_.]|__|[-]*/
    //  tag                             := /[\w][\w.-]{0,127}/
    //  digest                          := digest-algorithm ":" digest-hex
    //  digest-algorithm                := digest-algorithm-component [ digest-algorithm-separator digest-algorithm-component ]
    //  digest-algorithm-separator      := /[+.-_]/
    //  digest-algorithm-component      := /[A-Za-z][A-Za-z0-9]*/
    //  digest-hex                      := /[0-9a-fA-F]{32,}/ ; At least 128 bit digest value

    The actual implementation of that is via a regex in distribution/reference/regexp.go.

    But with some digging and poking, I found that there’s another check beyond that regex (you’ll get errors with an uppercase hostname if you don’t don’t include a . or :). And I tracked down the actual split of the name to the following in docker/reference.go:

    func splitHostname(name string) (hostname, remoteName string) {
        i := strings.IndexRune(name, '/')
        if i == -1 || (!strings.ContainsAny(name[:i], ".:") && name[:i] != "localhost") {
            hostname, remoteName = DefaultHostname, name
        } else {
            hostname, remoteName = name[:i], name[i+1:]
        if hostname == LegacyDefaultHostname {
            hostname = DefaultHostname
        if hostname == DefaultHostname && !strings.ContainsRune(remoteName, '/') {
            remoteName = DefaultRepoPrefix + remoteName

    The important part of that for me is the check for the . and : before the first / in the first if statement. With it, the hostname is split out from before the first /, and without it, the entire name is passed to the default registry hostname.

    Docker will be the best open platform for developers and sysadmins to build, ship, and run distributed applications.