compose.yaml の volumes: に書く1行で、コンテナを消したあともデータが残るか、ホストのファイルをそのまま使えるか、docker compose down -v で消えるかが決まります。
Docker Composeのvolumesとは、コンテナの中のパスに、コンテナの外にある保存先をつなぐ設定です。つなぐ先は3種類です。DBなど残したいデータには名前付きボリューム、ソースコードや設定ファイルをホストと共有するならバインドマウント、残さない一時ファイルならtmpfsを選びます。
見分けるコツは、コロンの左側です。db-data のような名前なら名前付きボリューム、./html のようなパスならバインドマウントになります。
この記事でわかること
- 名前付きボリューム・バインドマウント・tmpfsの違いと選び方
compose.yamlの短い書き方と長い書き方(docker compose configの実行結果つき)- トップレベルの
volumes:が必要な理由と、external・nameの使いどころ - 読み取り専用(
ro)の指定と、docker compose down -vで消えるもの・消えないもの - tarでのバックアップと、別の名前・別のマシンへの移行
- Mac・Windows・Rancher Desktopでバインドマウントを使うときの注意
Composeの基本から知りたい方は、先にDocker Compose入門を読むと流れがつかめます。この記事は、そこで少しだけ触れたvolumesを、書き方から消え方まで掘り下げる位置づけです。docker volume prune などの掃除コマンドはdocker pruneの使い方に任せ、ここでは「Composeの設定として何を書けばどうなるか」に絞ります。
PARTS LIST /目次
3種類のマウントの違いと選び方
Dockerがコンテナにデータをつなぐ方法は、名前付きボリューム、バインドマウント、tmpfsの3つです。違いは「データが実際にどこにあるか」と「コンテナを消したとき残るか」の2点で整理できます。
最初に比較表で全体像をつかみ、そのあと判断の流れを見ます。
名前付きボリューム・バインドマウント・tmpfsの比較
ボリュームはDockerが管理し、ホストのファイルシステムから隔離されています。ホストから直接ファイルを触る用途には向かないので、その場合はバインドマウントを使います。バックアップや移行はボリュームのほうが楽で、コンテナの書き込みレイヤーに書くより高速です。
tmpfsはデータをホストのメモリ上にだけ置き、コンテナが止まると消えます。Linuxでしか使えず、コンテナ間で共有もできません。
匿名ボリュームという4つめの形もあります。コロンの左側を書かず、/var/lib/data のようにコンテナ側のパスだけを書くと、ランダムな名前のボリュームが作られます。名前で追いかけられないので、永続化したいデータには向きません。
迷ったときの選び方
選び方は、2つの質問に答えるだけで決まります。
最初の質問は「ホストのエディタやGitから、そのファイルを直接触るか」です。触るならバインドマウントです。触らないなら次の質問に進みます。
次の質問は「コンテナを消しても残したいか」です。DBのデータやアップロードされたファイルなら残したいので名前付きボリューム、キャッシュや一時ファイルならtmpfsが候補になります。
flowchart TD
A{"ホストから<br>直接触る?"}
A -->|"はい(ソース・設定)"| B["バインドマウント"]
A -->|"いいえ"| C{"コンテナを消しても<br>残したい?"}
C -->|"はい(DB・画像)"| D["名前付きボリューム"]
C -->|"いいえ(一時ファイル)"| E["tmpfs(Linuxのみ)"]
開発中のコードはバインドマウント、DBのデータは名前付きボリューム、という組み合わせが定番です。1つのサービスに3種類を混ぜても問題ありません。
空のボリュームにはイメージのファイルがコピーされる
名前付きボリュームとバインドマウントには、見落としやすい違いがもう1つあります。コンテナ側のマウント先にすでにファイルがあるときの動きです。
空の名前付きボリュームをマウントすると、マウント先にあるイメージのファイルがボリュームにコピーされます。存在しない名前を指定した場合も、空のボリュームが自動で作られて同じようにコピーされます。
バインドマウントは逆で、ホスト側のディレクトリがイメージ側のファイルを覆い隠します。ホスト側が空なら、コンテナからは空のディレクトリに見えます。マウントを外してコンテナを作り直さない限り、隠れたファイルは戻りません。
「バインドマウントにしたら、イメージに入っていた設定ファイルが消えた」という症状は、たいていこの動きが原因です。
volumesの書き方|短い書き方と長い書き方
サービスの volumes: には、1行で書く短い書き方と、項目を分けて書く長い書き方があります。どちらも同じ設定を表せます。まず短い書き方から見ます。
短い書き方|コロンの左側で種類が決まる
短い書き方は ソース:コンテナ内のパス:モード の形です。ソースが名前なら名前付きボリューム、パスならバインドマウントとして扱われます。
services:
db:
image: postgres:17
volumes:
- db-data:/var/lib/postgresql/data
web:
image: nginx:1.27
volumes:
- ./html:/usr/share/nginx/html:ro
tmpfs:
- /var/cache/nginx
volumes:
db-data:
db サービスは名前付きボリューム db-data を、web サービスはカレントの html ディレクトリを読み取り専用でマウントしています。tmpfs: は volumes: とは別のキーです。
名前とパスの見分け方には落とし穴があります。相対パスは . か .. で始めるのが推奨で、html:/usr/share/nginx/html と書くと html という名前のボリュームとして扱われます。ホストのディレクトリをつなぎたいときは、必ず ./ から書きます。
モードは3つめの要素として書きます。
z と Z は、SELinuxのない環境では無視されます。SELinuxが有効なLinuxで、バインドマウントしたファイルに「Permission denied」が出るときに登場するオプションです。
長い書き方|typeを明示する
長い書き方は、type・source・target を項目として並べます。短い書き方で表せない設定、たとえば「ホスト側にパスがないときにエラーにする」「tmpfsのサイズを決める」は、こちらでしか書けません。
services:
db:
image: postgres:17
volumes:
- type: volume
source: db-data
target: /var/lib/postgresql/data
web:
image: nginx:1.27
volumes:
- type: bind
source: ./html
target: /usr/share/nginx/html
read_only: true
bind:
create_host_path: false
- type: tmpfs
target: /var/cache/nginx
tmpfs:
size: 67108864
volumes:
db-data:
主な項目は次のとおりです。
長い書き方は行数が増えますが、type が書いてあるので、読む人が名前かパスかを推測しなくて済みます。チームで読む設定では、この明示性が効きます。
docker compose configで正規化した結果を見る
短い書き方と長い書き方が同じ意味になることは、docker compose config で確かめられます。このコマンドはComposeファイルを読み込んで、省略を補った形で表示します。Dockerのデーモンが動いていなくても実行できます。
短い書き方のファイルを渡すと、次のように長い書き方へ展開されます(Docker Compose v2.32.1で確認。パスは作業フォルダの例)。
name: demo-short
services:
db:
image: postgres:17
networks:
default: null
volumes:
- type: volume
source: db-data
target: /var/lib/postgresql/data
volume: {}
web:
image: nginx:1.27
networks:
default: null
tmpfs:
- /var/cache/nginx
volumes:
- type: bind
source: /(作業フォルダの絶対パス)/demo-short/html
target: /usr/share/nginx/html
read_only: true
bind:
create_host_path: true
networks:
default:
name: demo-short_default
volumes:
db-data:
name: demo-short_db-data
見どころは3つあります。
db-dataがtype: volumeに、./htmlがtype: bindに展開され、相対パスは絶対パスに変わる- 短い書き方のバインドマウントには
create_host_path: trueが補われる - ボリュームの実際の名前は、プロジェクト名(既定ではフォルダ名)を前に付けた
demo-short_db-dataになる
最後の点は、あとでバックアップを取るときに効きます。docker volume ls に並ぶのは、db-data ではなく プロジェクト名_db-data のほうだからです。
手元のMacではRancher DesktopでDockerを動かしています。この記事を書いている間は起動していなかったので、docker compose up は使えませんでした。そこで、設定の読み込みだけで済む docker compose config を使い、上の展開結果と、のちに出てくる「宣言漏れ」のエラーを実行して確かめています。YAMLの書き間違いは、コンテナを起動する前にここで見つかります。
トップレベルのvolumesが必要な理由
名前付きボリュームを使うときは、サービスの中に加えて、ファイルの一番外側にも volumes: を書きます。サービス側は「どのボリュームをどこにつなぐか」、トップレベルは「そのボリュームがどういうものか」を定義する場所です。
トップレベルに書かずにサービスだけで名前を使うと、Composeが止めます。docker compose config で確かめると、次のエラーになりました。
service "db" refers to undefined volume db-data: invalid compose project
バインドマウントは名前を持たないので、トップレベルの宣言は要りません。宣言が必要なのは名前付きボリュームだけです。
空の定義とプロジェクト名の接頭辞
トップレベルの db-data: は、中身が空でかまいません。空にすると、コンテナエンジンの既定の設定で名前付きボリュームが作られます。
Composeは、name を指定しない限り、ボリューム名の前にプロジェクト名を付けます。さきほどの出力で demo-short_db-data になっていたとおりです。同じ compose.yaml を別のフォルダにコピーして up すると、別のプロジェクトとして扱われ、別名のボリュームが新しく作られます。
「フォルダ名を変えたら、DBが空になった」という現象はこの仕組みが原因です。データが消えたのではなく、古い名前のボリュームに残ったまま、新しい名前の空のボリュームが作られています。気づいたら docker volume ls で両方を探します。
external・name・driver_optsの使いどころ
トップレベルの volumes: には、名前以外にもいくつか項目を書けます。
external: true は、プロジェクトをまたいで同じデータを使いたいときや、down でも消したくない大事なボリュームに使います。Composeはそのボリュームを作らず、存在しなければエラーにします。name と組み合わせると、ファイル内の呼び名と実際のボリューム名を分けられます。
volumes:
db-data:
external: true
name: shared-db-data
この設定では、サービスは db-data と呼び、実際には shared-db-data という既存のボリュームがつながります。docker compose config の出力でも name: shared-db-data と external: true が並ぶことを確認しました。事前に docker volume create shared-db-data で作っておく必要があります。
local ドライバーに type: none・o: bind・device: /srv/app-data を渡すと、名前付きボリュームの形でホストの特定のパスを指せます。device のパスは事前に存在している必要があります。ボリュームの管理コマンドに乗せつつ、置き場所だけ指定したいときの手段です。
複数のサービスで同じボリュームを共有する
トップレベルで宣言した名前付きボリュームは、複数のサービスから同じ名前で参照できます。アップロードされた画像をアプリが書き、別のコンテナが配信する、といった構成です。
services:
app:
image: my-app:latest
volumes:
- uploads:/var/www/uploads
web:
image: nginx:1.27
volumes:
- uploads:/usr/share/nginx/html/uploads:ro
volumes:
uploads:
書く側の app は読み書き、配信する側の web は ro にしています。同じボリュームでも、サービスごとに読み取り専用を分けられます。
読み取り専用にする
読み取り専用は、コンテナ側から書き込めないようにする設定です。設定ファイルや静的ファイルのように、コンテナが書き換える必要のないものに付けておくと、誤って壊す事故を減らせます。
短い書き方なら、末尾に :ro を付けます。
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
- ./html:/usr/share/nginx/html:ro
長い書き方なら read_only: true です。読み取り専用にすると、docker inspect の Mode が ro、RW が false になります。
バインドマウントはデフォルトで書き込み可能なので、コンテナがホストのファイルを書き換えられます。ホストのソースコードをバインドマウントするコンテナが、誤ってファイルを消す、という事故も起こり得ます。書かせる必要のないマウントは、最初から ro にしておくと安全です。
読み取り専用が使えない場面もあります。DBのデータ用ボリュームや、ログの書き出し先は書き込みが必要なので、rw のままにします。
html:/usr/share/nginx/html は、ボリューム名になるホストの html フォルダをつなぐつもりで ./ を付け忘れると、Composeは html という名前のボリュームだと解釈します。トップレベルに宣言がなければエラーで気づけますが、宣言もあると、空のボリュームが静かに作られて、ホストの編集がコンテナに反映されません。ホストのフォルダをつなぐときは、必ず ./ から書きます。
docker compose down -vで消えるもの・消えないもの
docker compose down は、コンテナとネットワークを削除するコマンドです。ボリュームは、既定では消えません。-v(--volumes)を付けたときだけ、消える対象に加わります。
down と down -v の違いは次のとおりです。
external のボリュームは、どのオプションを付けても削除されません。バインドマウントも、ボリュームではなくホストのファイルなので、down -v の対象になりません。DBのデータを消したくないのに down -v を打ってしまう事故が起きやすいので、本番に近い環境では external にしておくのが1つの対策になります。
匿名ボリュームは、down だけでは残りますが、名前が分からないので次の up で自動的にはつながりません。up するたびに新しい匿名ボリュームが作られ、古いものがディスクに溜まっていきます。永続化したいデータは、名前付きボリュームかバインドマウントにします。
down -v を打つ前に、docker volume ls で名前を見る名前付きボリュームは down -v で削除され、復元できません。やり直したいだけのつもりで付けたオプションでDBが空になる、という失敗は、ボリュームの中身を知らないまま打つと起きます。再作成したいだけなら docker compose down のあとに up -d で十分です。データごと作り直したいと決めたときだけ -v を付けます。
down -vとdocker volume pruneの違い
docker volume prune は、どのコンテナからも使われていないボリュームを削除するコマンドです。既定では匿名ボリュームだけが対象で、名前付きボリュームまで消すには -a(--all)を付けます。
down -v は「このComposeプロジェクトのボリューム」を対象にし、volume prune は「どのコンテナからも使われていないボリューム」を対象にします。範囲の決め方が違うので、混ぜて考えないようにします。
Composeを止めたあとの掃除や、ディスク容量を空ける場面の考え方は、docker pruneの使い方にまとめています。10月にMacの容量を整理したとき、Rancher Desktopのデータは約11GBありましたが、そのときは手を付けずに残しました。ボリュームの中身は名前を見るだけでは分からないので、消す前の確認が欠かせません。
バックアップと別環境への移行
名前付きボリュームの中身は、Dockerが管理する領域に入っているため、ホストのファイルのように直接コピーできません。バックアップや移行では、ボリュームをマウントした一時的なコンテナを作り、その中から取り出します。
tarでバックアップして戻す
Dockerの定番は、--volumes-from で対象のボリュームをマウントしたコンテナを作り、tar で固める方法です。Composeで作ったボリュームなら、ボリューム名を直接 -v に渡す形のほうが分かりやすく書けます。
step
1ボリュームの実名を調べる
docker volume ls
Composeが作ったボリュームは プロジェクト名_db-data の形で並びます。以下では myproject_db-data とします。
step
2サービスを止めてからtarで固める
docker compose stop db
docker run --rm \
-v myproject_db-data:/data:ro \
-v "$(pwd)":/backup \
alpine tar czf /backup/db-data.tar.gz -C /data .
ボリュームは ro でマウントして、バックアップ中に書き換えないようにしています。カレントディレクトリに db-data.tar.gz ができます。
step
3新しいボリュームに展開して戻す
docker run --rm \
-v myproject_db-data:/data \
-v "$(pwd)":/backup \
alpine tar xzf /backup/db-data.tar.gz -C /data
存在しないボリューム名を指定すると、空のボリュームが自動で作られてから展開されます。別のマシンに移すときは、db-data.tar.gz を scp などで運び、移行先で同じコマンドを実行します。
DBは動いたまま取れるダンプを使う
DBのデータ用ボリュームを、稼働中にtarで固めても、書き込み途中のファイルを拾って壊れたバックアップになることがあります。DBは、サービスを止めてからtarにするか、DB自身のダンプ機能を使うのが確実です。
PostgreSQLなら pg_dump を docker compose exec で呼びます。
docker compose exec -T db pg_dump -U postgres mydb > mydb.sql
戻すときは、同じ形で psql に流し込みます。
docker compose exec -T db psql -U postgres mydb < mydb.sql
ダンプはSQLの文字列なので、DBのバージョンやボリュームの名前に依存せず、別の環境にも持ち出せます。コンテナの中に入って確かめたいときは、Dockerコンテナに入る方法の exec が使えます。
ボリュームの名前を変えて引き継ぐ
プロジェクト名を変えたい、external に切り替えたい、というときは、古いボリュームから新しいボリュームへ中身をコピーします。ボリュームの名前そのものは変更できないからです。
docker volume create new-db-data
docker run --rm \
-v myproject_db-data:/from:ro \
-v new-db-data:/to \
alpine cp -a /from/. /to/
コピーしたら、compose.yaml のトップレベルを external: true と name: new-db-data に書き換えて up します。古いボリュームは、新しい環境でデータを確認してから消します。
Mac・Windows・Rancher Desktopでバインドマウントを使う注意
バインドマウントは、Linux以外では「ホストのファイルを直接共有している」わけではありません。Docker DesktopもRancher Desktopも、Dockerのデーモンは仮想マシンの中のLinuxで動いています。ホストのフォルダは、その仮想マシンに共有する仕組みを通して見えています。
この共有を挟むかどうかで、速度と動きが変わります。名前付きボリュームは仮想マシンの中に閉じているので、共有を通りません。
Macでは共有されるフォルダが決まっている
Docker Desktop for Macで、バインドマウントとして使えるのは、既定で共有されている /Users・/Volumes・/private・/tmp・/var/folders の下です。プロジェクトがこの外にあると、「Mounts denied」や「cannot start service」のエラーになることがあります。その場合は、設定で共有するフォルダを追加します。
共有の実装は、アプリによって違います。
Rancher Desktopの入れ方と設定は、Rancher DesktopのMacインストールにまとめています。
大量の小さなファイルを読み書きするプロジェクト(node_modules など)をバインドマウントすると、共有を通るぶん遅く感じることがあります。そういう場所だけを名前付きボリュームに逃がす構成も、よく使われます。
Windowsでは、WSL 2のLinux側にプロジェクトを置く
Docker DesktopでWSL 2を使うときは、プロジェクトやバインドマウントするデータを、Linuxのファイルシステムの中に置くのが推奨です。
- Linuxのファイルシステム上のファイルでないと、コンテナがファイル変更の通知(inotify)を受け取れない。自動リロードが効かなくなる原因になる
- Linux側のファイルをバインドマウントするほうが、Windows側のファイルを使うより大幅に速い
docker run -v /mnt/c/users:/usersのように、/mnt/c経由でWindows側のパスをマウントするのは避ける
勧められている書き方は、LinuxのシェルでホームのプロジェクトをマウントするDockerコマンドです。
docker run -v ~/my-project:/sources my-image
Composeでも同じで、プロジェクトのフォルダをWSLのホーム(~/my-project)に置き、そこで docker compose up を実行します。
存在しないパスは、勝手にディレクトリになる
バインドマウントの左側に、存在しないパスを書いたときの動きは、書き方で変わります。
compose.yamlの短い書き方やdocker run -vでは、ホスト側にディレクトリが自動で作られる。ファイルのつもりでも、作られるのはディレクトリdocker run --mountでは、既定でエラーになる- 長い書き方で
create_host_path: falseを指定すると、Composeでも作らずにエラーにできる
./config.yaml:/app/config.yaml と書いたのにファイルがなかった場合、config.yaml という名前の空のディレクトリができて、アプリが「設定ファイルが読めない」と言い出します。原因が分かりにくいので、重要なファイルは長い書き方で create_host_path: false にしておくと、起動時にエラーとして気づけます。
Linuxでは、ファイルの所有者に注意する
Linuxのホストでは、コンテナがrootで動いているとき、バインドマウントしたディレクトリに作られるファイルの所有者もrootになります。ホストのユーザーで編集しようとすると、権限エラーになります。
対策は、コンテナを動かすユーザーをホストのユーザーに合わせることです。compose.yaml の user: に、id -u と id -g で調べた数値を指定します。ボリューム・権限まわりのエラーの対処は、Docker Compose入門の「ボリューム・権限エラー」の節にもまとめています。
よくある質問
Q1. docker compose volumesの「:」の左側は何を書けばいい?
名前を書くと名前付きボリューム、./ か / から始まるパスを書くとバインドマウントになります。. か .. で始まらない文字列は名前として扱われるので、ホストのフォルダをつなぐときは ./ を必ず付けます。
Q2. 名前付きボリュームとバインドマウントはどちらを使えばいい?
DBのデータなど、コンテナを消しても残したいものには名前付きボリュームです。ソースコードや設定ファイルのように、ホストのエディタで編集したいものにはバインドマウントです。Mac・Windowsでは、名前付きボリュームのほうが共有を挟まないぶん速い傾向があります。
Q3. docker compose down でボリュームは消える?
消えません。docker compose down はコンテナとネットワークを削除するだけです。-v を付けると、トップレベルで宣言した名前付きボリュームとコンテナに付いた匿名ボリュームが削除されます。external: true のボリュームは、-v を付けても消えません。
Q4. ボリュームの中身はどこで見られる?
docker volume inspect ボリューム名 の Mountpoint で場所を確認できます。Linuxでは /var/lib/docker/volumes/ボリューム名/_data の下にあります。Mac・Windowsでは仮想マシンの中にあるので、ホストのFinderやエクスプローラーでは見えません。中身を見るなら、そのボリュームをマウントした一時コンテナで ls します。
Q5. フォルダ名を変えたらDBが空になったのはなぜ?
Composeは、ボリューム名の前にプロジェクト名(既定ではフォルダ名)を付けるためです。フォルダ名が変わると別のプロジェクトとして扱われ、新しい空のボリュームが作られます。古いデータは、古い名前のボリュームに残っています。docker volume ls で探して、external: true と name で指定し直せば使えます。
Q6. tmpfsはいつ使う?
ディスクに残したくない一時ファイルや、書き込みの多いキャッシュに使います。データはホストのメモリ上に置かれ、コンテナが止まると消えます。Linuxのホストでしか使えず、コンテナ間では共有できません。また、tmpfsの使用量はコンテナのメモリ上限に含まれます。
Q7. バインドマウントしたら、コンテナ内の元のファイルが消えた?
消えたのではなく、隠れています。マウント先にホストのディレクトリが重なるため、イメージにあったファイルが見えなくなります。マウントを外してコンテナを作り直すと戻ります。イメージの初期データを残したい場合は、名前付きボリュームを使います。空のボリュームなら、イメージのファイルがコピーされます。
まとめ:volumesは「名前か、パスか」から決める
volumesは、コロンの左側が名前かパスかで意味が変わります。名前なら名前付きボリューム、パスならバインドマウントで、残さない一時ファイルは tmpfs: に書きます。
名前付きボリュームを使うなら、トップレベルの volumes: への宣言が要ります。down -v で消えるのはその名前付きボリュームと匿名ボリュームで、external とバインドマウントしたファイルは消えません。
docker compose config を実行して、volumes が長い書き方でどう展開されるか見てみる。デーモンが動いていなくても実行できます。コロンの左側が名前かパスか、ボリュームの実名がどうなるかを、起動する前に確かめられます。
続きを追う:X(@Tom_Java_Tech) / RSS
途中経過は、また書きます。

