How is Docker Compose version 2 "volumes" syntax supposed to look?

With Docker Compose v1.6.0+, there now is a new/version 2 file syntax for the docker-compose.yml file. The changes include a separate top level key named volumes. This allows to "centralize" volume definitions in one place.

What I am trying to do is to name volumes in there and have a single volume reference multiple path on my local host disk. The following is an example, throwing an exception with a Traceback that ends with

AttributeError: 'list' object has no attribute 'items'

Example docker-compose.yml:

version: '2'

    image: postgres
      - database:/var/lib/postgres/data

    image: php-fpm:5.6
      - phpconf:/etc/php/conf.d

    container_name: namedvolume
    build: ./Docker/Testvolume
      - ./Docker/Testvolume/shareme

    - ./Docker/Postgres/db:ro
    - ./Docker/Postgres/ini
    - ./Docker/PHP-FPM/conf
  singledir: ./Docker/foo
  completemap: ./Docker/bar:/etc/service/conf.d
  - namedvolume:/etc/service/conf.d # < this was a separate attempt w/o the other keys
  … ?

So far I read through all the Docker Compose docs master-branch Volume configuration reference, the Docker Compose docs Volume/Volume-Driver reference and looked through GitHub examples to find the correct syntax that is expected. It seems no one is already using that (GitHub) and the documentation is far from being complete ( I also tried to build a separate volume as service and reference it in volumes, but that does not work as well. Any idea on how to this syntax is supposed to look like?

Purpose of the volumes key

It is there to create named volumes.

If you do not use it, then you will find yourself with a bunch of hashed values for your volumes. Example:

$ docker volume ls 
local               f004b95d8a3ae11e9b871074e9415e24d536742abfe86b32ffc867f7b7063e55
local               9a148e167e1c722cbdb67c8edc36f02f39caeb2d276e9316e64de36e7bc2c35d

With named volumes, you get something like the following:

$ docker volume ls
local               projectname_someconf
local               projectname_otherconf

How to create named volumes

The docker-compose.yml syntax is:

version: '2'

container_name: app
- appconf
container_name: appconf
- ./Docker/AppConf:/var/www/conf


driver: bridge

This something like above shown named volumes.

How to remove volumes in bulk

When you have a bunch of hashes, it can be quite hard to clean up. Here's a one-liner:

docker volume rm $(docker volume ls |awk '{print $2}')

Edit: As @ArthurTacca pointed out in the comments, there's an easier to remember way:

docker volume rm $(docker volume ls -q)

How to get details about a named volume

Now that you do not have to look up hashes anymore, you can go on it and call them by their … name:

docker volume inspect <volume_name>


$ docker volume inspect projectname_appconf

"Name": "projectname_appconf",
"Driver": "local",
"Mountpoint": "/mnt/sda1/var/lib/docker/volumes/projectname_appconf/_data"

Sidenote: You might want to docker-compose down your services to get a fresh start before going to create volumes.

In case you are using Boot2Docker/ Docker Machine, you will have to docker-machine ssh and sudo -i before doing a ls -la /mnt/… of that volume – you host machine is the VM provisioned by Docker Machine.

EDIT: Another related answer about named volumes on SO.

The way I understand it, you can use the global volumes: section to

  • define a volume name
  • make an named volume available under a different volume name
  • specify a driver and driver options for a named volume

Volumes in the global section will be auto-created unless you specify external: true. You will still need to tell each service in its volumes: section where to mount that volume.

Here's a very simple example:

version: '2'
      - project:/bar
      - project:/foo

The global volumes: entry for project will cause a named volume project to be created. It then gets mounted as /bar in service one, and as /foo in service two. Both services share the volume's data and can read/write it.

I don't think that what you are trying to do is possible (turning multiple paths into a single volume, and with different r/w flags). If it is possible, then probably by finding a way to create a named volume with these properties through some other means and then adding it as an external volume:

    external: true

I think what you're trying to do is roughly the same as seen here. In short: it's currently not possible to create a named volume that refers to a mount point on the host. You can create a named volume to share data between containers, but the data will only exist in the volume itself, and disappear when you delete the volume.

Mounting named volumes has been proposed, but unfortunately it won't be added to the core in the near future. However, it is possible by using a docker plugin named local-persist.

Check out Version 2 for example, also Volume configuration reference:

My example: (Version 1)

$ tail -4 docker-compose.yml 
    - ./etc/nginx/conf.d:/etc/nginx/conf.d:ro
    - ./var/log/nginx:/var/log/nginx:rw
    - ./var/www/html:/var/www/html:rw