YAMLの書き方入門|インデント・リスト・型の落とし穴とよくあるエラーの直し方
GitHub Actions のワークフロー、Docker Compose、各種ツールの設定ファイルなど、開発では YAML(ヤムル)という形式のファイルをよく使います。書き方はシンプルですが、「スペースが 1 つずれただけでエラーになる」「NO と書いたら false になった」「1.10 が 1.1 になった」など、知らないとはまる落とし穴がいくつもあります。
この記事では、YAML の基本の書き方と型の落とし穴、よくあるエラーの読み方を、Windows 11・Python 3.12.6・PyYAML 6.0.3 で実際に読み込んだ結果つきで説明します。仕様の説明は、YAML の公式仕様 YAML 1.2.2(2021 年 10 月 1 日改訂)で確認しています。
この記事で分かること
- キーと値・インデント・リスト・コメント・引用符・複数行の文字列の書き方
yes・NO・0123・1.10・日付などが勝手に別の型になる落とし穴と、YAML 1.1 と 1.2 の違い- タブ・インデントのずれ・コロンの後のスペース忘れで出るエラーと直し方
- YAML と JSON の対応と、Python での変換方法
YAML とは?
YAML は、データを人が読み書きしやすい形で表すための書式です。主に設定ファイルに使われ、拡張子は .yaml または .yml です。JSON と同じように「キーと値の組(辞書)」や「リスト」を表せますが、波かっこ {} やダブルクォート " を使わず、インデント(行頭のスペース)で入れ子を表すのが大きな特徴です。記号が少なくコメントも書けるので手で編集しやすい反面、見た目のずれがそのまま意味の違いになります。
確認用のスクリプトを用意する
この記事では、YAML がどう読み込まれたかを Python の YAML ライブラリ PyYAML を使って確かめます。まず PowerShell で PyYAML を入れます(pip の使い方は「pipの使い方」で説明しています)。
py -m pip install pyyaml
次のコードを check.py として保存します。YAML ファイルを読み込んで Python のデータとして表示し、書き間違いがあればエラーメッセージを表示します。
import sys
import yaml
with open(sys.argv[1], encoding="utf-8") as f:
try:
data = yaml.safe_load(f)
print(data)
except yaml.YAMLError as e:
print(e)
読み込みには yaml.load ではなく yaml.safe_load を使います。PyYAML の公式ドキュメントには「信頼できない場所から受け取ったデータで yaml.load を呼ぶのは安全ではない」「任意の Python の関数を呼び出せる」と書かれています。safe_load は数値・文字列・リストなどの基本的なデータしか作りません。
YAML の基本の書き方
キーと値は「キー: 値」で書く
1 行に 1 組ずつ、キー: 値 の形で書きます。コロンの後には必ず半角スペースを 1 つ以上入れます。次の内容を config.yaml として保存します。
# アプリの設定ファイル(例)
app_name: sample-app
port: 8080
debug: false
database:
host: localhost
port: 5432
name: sample_db
admins:
- tanaka
- sato
py check.py config.yaml
{'app_name': 'sample-app', 'port': 8080, 'debug': False, 'database': {'host': 'localhost', 'port': 5432, 'name': 'sample_db'}, 'admins': ['tanaka', 'sato']}
引用符で囲んでいない sample-app は文字列、8080 は整数(int)、false は真偽値(bool)として読み込まれました。YAML は値の見た目から型を自動で判定します(これが後で説明する落とし穴の原因です)。
インデントで入れ子を表す(スペースのみ・タブは不可)
上の例の database: のように、値を書かずに改行し、次の行から字下げしたキーを並べると、「辞書の中の辞書」になります。仕様では、インデントは行頭のスペースの数で表し、子は親より深く、同じ階層の項目はまったく同じ数だけ字下げすると決められています。タブ文字はインデントに使えません(システムによってタブの幅の扱いが違うため)。スペースの数(2 つか 4 つか)は決められておらず、同じ階層でそろっていれば読み込めます。
リストは「- 」で書く
リスト(配列)は、各要素の前に - (ハイフンと半角スペース)を付けます。リストの要素を辞書にするときは、- の後に 1 つ目のキーを書き、2 つ目以降のキーは 1 つ目のキーと同じ位置にそろえます。次の内容を nest.yaml として保存し、py check.py nest.yaml で読み込みます。
server:
host: localhost
port: 8080
users:
- name: tanaka
role: admin
- name: sato
role: viewer
{'server': {'host': 'localhost', 'port': 8080}, 'users': [{'name': 'tanaka', 'role': 'admin'}, {'name': 'sato', 'role': 'viewer'}]}
server の下は 4 つのスペースで字下げしましたが、問題なく読み込めました。users の下の - は字下げしていませんが、これも正しい書き方です( - name: tanaka のように字下げしても同じ結果になります)。role は name と同じ列にそろえているので、同じ辞書のキーになります。
短いリストや辞書は、JSON と同じように [ ] と { } を使って 1 行で書くこともできます(フロースタイルといいます)。
branches: [main, develop]
db: {host: localhost, port: 5432}
コメントは「#」
# から行末まではコメントになります。仕様では「コメントは、ほかの部分と空白で区切らなければならない」とされていて、# の前にスペースがないとコメントになりません。次の内容を comment.yaml として保存し、py check.py comment.yaml で読み込みます。
# 行頭からのコメント
port: 8080 # 行の途中からのコメント
url: https://example.com/#top
color: #ff0000
{'port': 8080, 'url': 'https://example.com/#top', 'color': None}
URL の中の #top は前にスペースがないので、値の一部として残りました。一方、color: #ff0000 は # の前にスペースがあるため、#ff0000 がまるごとコメントになり、値は空(None)になってしまいました。色コードのように # で始まる値は、color: "#ff0000" のように引用符で囲みます。
文字列の引用符:いる・いらない
YAML の文字列は、多くの場合は引用符なしで書けます。ただし、次のような値は引用符で囲む必要があります。
| こんな値 | 引用符がないとどうなるか | 書き方の例 |
|---|---|---|
# で始まる | コメントになり、値が空になる | color: "#ff0000" |
| 途中に「: 」(コロン+スペース)を含む | エラーになる | message: "Error: not found" |
[・{・*・& などの記号で始まる | リストや辞書などとして解釈されてエラーになる | title: "[WIP] fix" |
| 数値・真偽値・日付に見える文字列 | 別の型になる(次の章で説明) | version: "1.10" |
引用符には、シングルクォート '…' とダブルクォート "…" の 2 種類があり、バックスラッシュ(\)の扱いが違います。次の内容を quotes.yaml として保存して確かめます。
plain: C:\Users\name\data
single: 'C:\Users\name\data'
double: "C:\\Users\\name\\data"
tab_in_double: "A\tB"
tab_in_single: 'A\tB'
check.py で読み込むと、plain・single・double の 3 つはどれも同じ「C:\Users\name\data」になりました。tab_in_double は A と B の間にタブ文字が入り、tab_in_single は「A\tB」という 4 文字のままです。
- 引用符なし・シングルクォート:
\は普通の文字。Windows のパスや正規表現はそのまま書ける。シングルクォートの中で'を書くときは''と 2 つ重ねる - ダブルクォート:
\t(タブ)や\n(改行)などのエスケープが使える。その代わり、\そのものは\\と書く
ダブルクォートの中に Windows のパスをそのまま書くと、\U が「Unicode の文字番号を 8 桁で書くエスケープ」と解釈されてエラーになります(path_ng.yaml の内容は path: "C:\Users\name\data")。
while scanning a double-quoted scalar
in "path_ng.yaml", line 1, column 7
expected escape sequence of 8 hexadecimal numbers, but found 's'
in "path_ng.yaml", line 1, column 12
パスや正規表現のように \ を含む文字列は、シングルクォートで囲むのが安全です。
複数行の文字列:「|」と「>」
シェルのコマンドや長い説明文など、複数行の文字列は | か > を使って書きます。次の内容を multiline.yaml として保存し、py check.py multiline.yaml で読み込みます。
literal: |
1行目
2行目
folded: >
これは長い説明文を
複数行に分けて書いたものです。
空行は改行になります。
strip: |-
末尾の改行なし
{'literal': '1行目\n2行目\n', 'folded': 'これは長い説明文を 複数行に分けて書いたものです。\n空行は改行になります。\n', 'strip': '末尾の改行なし'}
| は書いたとおりに改行が残るので、シェルのコマンドに向いています。> は改行が半角スペースに変わって 1 行につながり、空行の所だけが改行になります。上の結果でも「説明文を 複数行に」のように日本語の途中にスペースが入りました。どちらも最後に改行が 1 つ付き、|-・>- と書くと最後の改行は付きません。
同じ内容を使い回す:アンカー「&」とエイリアス「*」
&名前 を付けた値(アンカー)は、ほかの場所から *名前(エイリアス)で参照できます。次の内容を anchor.yaml として保存し、py check.py anchor.yaml で読み込みます。
defaults: &db_default
host: localhost
port: 5432
development:
database: *db_default
test:
database:
<<: *db_default
port: 5433
{'defaults': {'host': 'localhost', 'port': 5432}, 'development': {'database': {'host': 'localhost', 'port': 5432}}, 'test': {'database': {'host': 'localhost', 'port': 5433}}}
development には defaults の内容がそのまま入りました。test の <<:(マージキー)は、defaults の内容を取り込んで port だけを上書きしています。マージキーは YAML 1.1 の追加の型で、YAML 1.2.2 の仕様本体には含まれていないため、使うツールが対応しているか確かめてから使いましょう。
型の自動判定の落とし穴
YAML でいちばんはまりやすいのが、引用符なしで書いた値の型の自動判定です。しかも、判定の規則は YAML の仕様のバージョン(1.1 と 1.2)で違います。
YAML 1.1 と 1.2 の違い
YAML 1.2 は 2009 年に公開され、2021 年の改訂版が 1.2.2 です。1.2.2 の仕様書には、1.2 で「問題の多かった暗黙の型付けの推奨の多くを取り除いた」とあります。たとえば 1.1 の型の定義では y・n・yes・no・on・off(大文字も含む)も真偽値でしたが、1.2.2 の Core Schema では true・True・TRUE・false・False・FALSE だけです。
ところが、Python でよく使われる PyYAML は YAML 1.1 に沿ったライブラリです。PyYAML の公式サイトには、特長として「完全な YAML 1.1 のパーサー」と書かれています。
PyYAML での実際の結果
引用符なしで書いた値を PyYAML 6.0.3 の safe_load で読み込んだ結果です。右の列は YAML 1.2.2 の Core Schema の規則の表から読み取ったもので、パーサーで試したものではありません。
| 書いた値 | PyYAML(YAML 1.1)の結果 | YAML 1.2.2 Core Schema の規則では |
|---|---|---|
yes / on | True(bool) | 文字列 |
no / off / NO | False(bool) | 文字列 |
y / n | 'y' / 'n'(文字列) | 文字列 |
0123 | 83(8 進数として読まれる) | 123(整数) |
1e3 | '1e3'(文字列) | 1000.0(小数) |
1.0e+3 | 1000.0(float) | 1000.0(小数) |
1.10 | 1.1(float) | 1.1(小数) |
2026-10-18 | datetime.date(2026, 10, 18) | 文字列 |
22:30 | 1350(60 進数として読まれる) | 文字列 |
~ / 空 | None | null |
ノルウェー問題:NO が false になる
国コードの一覧を書いたとき、ノルウェーの NO だけが false になってしまう現象は「ノルウェー問題」と呼ばれ、YAML 1.1 の落とし穴の代表例です。次の内容を norway.yaml として保存し、py check.py norway.yaml で読み込みます。
countries: [JP, US, NO]
{'countries': ['JP', 'US', False]}
選択肢の yes・no や on・off も真偽値になります。文字列として使うときは引用符で囲みます。
バージョン番号・郵便番号・時刻・日付
- バージョン番号:
1.10や3.10は小数として読まれ、1.1・3.1になる。これは YAML 1.2 の規則でも同じなので、バージョンは常に引用符で囲む - 0 で始まる番号:郵便番号や社員番号の
0123は、PyYAML では 8 進数として 83 になる。1.2 の規則でも先頭の 0 は消えて 123 になる - 時刻:
22:30は PyYAML では 60 進数として 22×60+30=1350 になる - 日付:
2026-10-18は PyYAML では Python の date 型になる。そのままjson.dumpsするとTypeError: Object of type date is not JSON serializableになる
GitHub Actions 風のファイルを PyYAML で読むと
落とし穴がまとめて出る例として、GitHub Actions のワークフロー風のファイルを PyYAML で読んでみます。次の内容を workflow.yaml として保存し、py check.py workflow.yaml で読み込みます。
# テストを実行するワークフロー(GitHub Actions 風の例)
name: test
on:
push:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: [3.9, 3.10, "3.11"]
steps:
- uses: actions/checkout@v4
{'name': 'test', True: {'push': {'branches': ['main']}}, 'jobs': {'test': {'runs-on': 'ubuntu-latest', 'strategy': {'matrix': {'python-version': [3.9, 3.1, '3.11']}}, 'steps': [{'uses': 'actions/checkout@v4'}]}}}
2 つの問題が起きています。
- キーの
onが、文字列ではなくTrueになった。PyYAML でワークフローのファイルを読んで処理するスクリプトを書くときは、data["on"]では取り出せない 3.10が3.1になった。引用符で囲んだ"3.11"は文字列のまま残っている
読み込む側が YAML 1.1 と 1.2 のどちらに沿っているかで結果が変わるので、迷ったら引用符で囲むのが確実です。次のように囲むと、PyYAML でもすべて文字列のまま読み込まれました。
countries: [JP, US, "NO"]
zip: "0123"
version: "1.10"
time: "22:30"
answer: "yes"
よくあるエラーとエラーメッセージの読み方
PyYAML のエラーメッセージには、問題の場所が line 3, column 8(3 行目の 8 文字目)のように示されます。ただし、本当の原因はその前の行にあることが多い点に注意してください。以下は check.py で表示されたメッセージです。
インデントにタブを使った
3 行目の port の前にタブ文字を入れたファイル(tab.yaml)です。
server:
host: localhost
port: 8080
while scanning for the next token
found character '\t' that cannot start any token
in "tab.yaml", line 3, column 1
'\t' はタブ文字のことです。エディターではスペースと見分けがつかないので、該当の行の行頭をスペースに打ち直します。なお、Windows で作った改行コードが CRLF の YAML は、PyYAML では LF のものと同じ結果で読み込めました(改行コードは「改行コードCRLFとLFの違い」で説明しています)。
インデントが深すぎる・浅すぎる
port の行だけスペースを 3 つにした(1 つ多い)場合です。
server:
host: localhost
port: 8080
mapping values are not allowed here
in "indent.yaml", line 3, column 8
「ここにはキーと値の組を書けない」という意味です。port が host より深いため、前の行の値の続き(「localhost port」という文字列)とみなされ、その後ろのコロン(8 文字目)で矛盾が起きています。
逆に、スペースを 1 つにした(1 つ少ない)場合は、別のメッセージになります。
while parsing a block mapping
in "indent2.yaml", line 1, column 1
expected <block end>, but found '<block mapping start>'
in "indent2.yaml", line 3, column 2
「1 行目から始まった辞書が終わるはずの所で、新しい辞書が始まった」という意味です。port が host とも server ともそろっていないので、どの階層に属するか決められません。
コロンの後のスペースを忘れた
コロンの後のスペースを忘れると、エラーにならずに文字列として読まれることがあります。name:test の 1 行だけのファイルを読むと、次のようになります。
name:test
辞書 {'name': 'test'} ではなく、「name:test」という 1 つの文字列になりました。設定が反映されないのにエラーが出ない、という分かりにくい不具合の原因になります。
入れ子の中で起きると、今度は次の行でエラーになります。
server:
host:localhost
port: 8080
mapping values are not allowed here
in "colon.yaml", line 3, column 7
2 行目の host:localhost が文字列になり、3 行目がその続きとみなされたためです。3 行目に問題が見つからないときは、前の行のコロンを確かめましょう。
値の中にコロンや記号がある
message: Error: not found のように、値の中に「: 」があるとエラーになります。
mapping values are not allowed here
in "colon2.yaml", line 1, column 15
また、title: [WIP] fix のように [ で始まる値はリストの書き始めとみなされ、expected <block end>, but found '<scalar>' というエラーになりました。どちらも、値全体を引用符で囲めば直ります(message: "Error: not found"、title: "[WIP] fix")。
YAML と JSON の対応
YAML 1.2.2 の仕様書には、YAML 1.2 の主な目的は「YAML を JSON の厳密な上位互換(strict superset)にすること」だったと書かれていて、JSON の書き方は基本的にそのまま YAML として読めます(小数の書き方など、完全には一致しない点も仕様書に注記されています)。実際に JSON ファイルを check.py で読み込めました。
| JSON | YAML(ブロックスタイル) | Python(PyYAML で読んだとき) |
|---|---|---|
{"key": "value"} | key: value | dict |
["a", "b"] | - a と - b を 1 行ずつ | list |
null | null・~・空 | None |
| (書けない) | # コメント | (読み込むと消える) |
YAML を JSON に変換する
YAML を読み込んで json.dumps で書き出せば、JSON に変換できます。次のコードを yaml2json.py として保存します。default=str は、日付のように JSON にできない値を文字列に変えるための指定です(json モジュールの使い方は「PythonでJSONを扱う方法」で説明しています)。
import json
import sys
import yaml
with open(sys.argv[1], encoding="utf-8") as f:
data = yaml.safe_load(f)
print(json.dumps(data, ensure_ascii=False, indent=2, default=str))
py yaml2json.py config.yaml
{
"app_name": "sample-app",
"port": 8080,
"debug": false,
"database": {
"host": "localhost",
"port": 5432,
"name": "sample_db"
},
"admins": [
"tanaka",
"sato"
]
}
先頭の # アプリの設定ファイル(例) というコメントは、JSON にはコメントがないため消えています。JSON の形を確かめたり構文エラーの場所を探したりするときは、JSON整形ツールに貼り付けると、整形とエラー位置の表示ができます(データはブラウザの中だけで処理され、外部には送られません)。
まとめ
- 「キー: 値」のコロンの後には必ずスペース。
#の前にスペースがあるとコメントになる - インデントはスペースだけ。同じ階層は同じ数のスペースでそろえる
yes・NO・0123・1.10・時刻・日付など、文字列として扱いたい値は引用符で囲む- PyYAML は YAML 1.1 に沿っている。読み込みには
safe_loadを使う - エラーの行番号の前の行も確かめる
関連する記事・ツール
- JSON整形ツール
- PythonでJSONを扱う方法|json.loads・dumpsの使い方とエラー対処
- Markdownの書き方入門:README.mdを一から書いて学ぶ表示の仕組みとつまずく点
- 改行コードCRLFとLFの違いと確認・変換方法|Gitのautocrlf設定も解説
- .envと環境変数で秘密情報を守る|APIキーをGitに上げない方法と漏れたときの対処
- pipの使い方|インストール・アップグレード・requirements.txtを実例で解説
- JSON・YAML・TOMLの違いと選び方|同じ設定を書き比べて分かる設定ファイルの特徴