【Python入門】YAMLファイルの書き方と使い方｜設定ファイルの操作をわかりやすく解説！

Q: YAMLとJSON、どちらを使えばいいの？

用途によって使い分けましょう！ JSON ：システム間のデータ通信（APIレスポンスなど）に向いています。マシンにとって扱いやすい形式。 YAML ：設定ファイルや構成定義など、人が手で編集する用途に適しています。読みやすさ重視。 Pythonではどちらも扱えますが、 設定ファイルにはYAML、通信にはJSON が一般的です。

Q: YAMLファイルを読み込むとエラーが出ます。何が原因？

インデントや記述ミスが多いです！ よくある原因は以下の通り： タブ（Tab）ではなく 半角スペースでインデント する必要がある : のあとにスペースがない リストの書き方（-）が間違っている クォートで囲むべき文字列（例: yes や 1234）を囲んでいない エディタにYAML構文チェッカーを入れるとミスに気づきやすくなります！

Q: safe_loadとloadの違いはなんですか？

safe_loadは安全な読み込み用、loadは高機能だけど危険な場合も。 safe_load() → 標準的なYAMLデータを安全に読み込む（おすすめ） load() → Pythonオブジェクトも読み込めるが、 信頼できないファイルでは使わないで！ 普段は safe_load() を使えばOKです。

1. はじめに｜YAMLってなに？Pythonで使うと何ができるの？
2. YAMLの基本構文と書き方
3. YAMLの発展的な書き方
4. PythonでYAMLファイルを読み書きする方法
5. よくあるミスとエラー対処
6. まとめ｜YAMLを使えば設定ファイルの管理がラクになる！
1. 🔑 今回のポイントをおさらい！
あわせて読みたい｜YAMLと相性のいいPython活用記事
1. 🔗 Pythonの設定ファイル・データ形式に関する記事
2. 🔗 Pythonのファイル操作や自動化に関する記事
よくある質問（Q&A）
1. 関連投稿:

1. はじめに｜YAMLってなに？Pythonで使うと何ができるの？

Pythonでプログラムを書いていると、
「設定値ってどこに書けばいいの？」
「コードを書き換えずに、動作だけ変えたい…」
と悩む場面、ありませんか？

たとえば、

デバッグモードをON / OFFで切り替えたい
環境ごとにデータベースのURLを変えたい
APIキーや設定値をコードから分離したい

こうしたケースでは、設定ファイルを使う設計がとても重要になります。

そこでよく使われるのが、YAML（ヤムル）ファイルです。
YAMLは、Pythonの辞書構造と相性がよく、人間にも読みやすい設定ファイル形式として、Webアプリ開発や業務スクリプト、API連携など幅広い現場で利用されています。

「JSONは触ったことがあるけど、YAMLは初めて」
「YAMLってインデントが難しそう…」

そんな不安を感じている方でも大丈夫です 😊
YAMLは基本ルールさえ押さえれば、Python初心者でも直感的に使えるファイル形式なんです。

この記事では、

YAMLファイルの基本的な書き方
PythonからYAMLを読み書きする方法
設定ファイルとしてYAMLを使うメリット

を中心に、初心者向けにやさしく・実例ベースで解説していきます。

Pythonでの設定管理を一段レベルアップしたい方は、ぜひ最後まで読んでみてください！

2. YAMLの基本構文と書き方

YAMLファイルは、Pythonで使われる辞書やリストに近い感覚で書けるのが特徴です。
ここではYAMLの基本的な書き方を、初心者向けにわかりやすく解説していきます！

2.1 キーと値の記述（基本のかたち）

YAMLの基本は「キー: 値」のペアで構成されています。

title: あなたのアプリ
version: 1.0
debug: true

値に文字列を書く場合、クォート（"や'）は基本不要です。
数値もそのまま書けます。
true / false / yes / no も真偽値として扱われます。
**null値（PythonでいうNone）**は null または ~ で表現します。

maintenance: false
max_users: 100
api_url: "https://example.com"  # 数値や真偽値と区別したいときはクォートを使う
description: null

2.2 リストの書き方（複数の値）

リスト（配列）を記述するには、各行の先頭に「ハイフン -」をつけます。

allow_hosts:
  - localhost
  - 127.0.0.1
  - 192.168.1.1

Pythonのリストと同じ感覚で使えます！

2.3 ネスト（入れ子）の書き方

値の中にさらに辞書（オブジェクト）を持たせたい場合は、インデントで階層を表現します。

database:
  host: localhost
  port: 3306
  username: user
  password: pass

✅インデントのルール

半角スペースでインデントします（タブは使いません！）
Pythonと同じく、階層ごとに2〜4つのスペースが一般的です（本記事では2スペース）

2.4 コメントの書き方

YAMLでは、# を使ってコメントを書くことができます。

debug: true  # デバッグモードを有効にする

設定ファイルとして使うとき、メモや注意点を残しておくのに便利です。

ここまでがYAMLの「基本のき」。
次はもう少し高度なテクニック――アンカー、マージ、複数行文字列などを紹介していきます！

3. YAMLの発展的な書き方

YAMLの基本的な書き方を覚えたら、次はもっと便利に使うためのテクニックを学びましょう。
ここでは、プロの現場でもよく使われる「アンカー」「マージ」「複数行文字列」などの発展的な記述方法をご紹介します！

3.1 アンカー（&）とエイリアス（*）

同じ内容を何度も書くのって面倒ですよね？
YAMLでは「アンカーとエイリアス」を使えば、値の再利用が可能です！

common_settings: &default_settings
  timeout: 30
  retries: 5

dev_env:
  <<: *default_settings  # 上の内容を再利用
  debug: true

prod_env:
  <<: *default_settings
  debug: false

✅ここがポイント

&名前 で再利用可能な設定（アンカー）を作る
*名前 でその設定（エイリアス）を呼び出す
<<: を使えば、辞書ごとマージできる（後述）

3.2 マージキー（<<:）

マージキーを使うと、複数の設定を1つに合体できます。

default: &default
  port: 8080
  host: localhost

custom:
  <<: *default  # 上の内容をマージ
  port: 9090    # 上書き可能

このように、再利用＆カスタマイズが簡単にできます。
設定ファイルをきれいに整理したいときにとても便利です！

3.3 複数行文字列の書き方

YAMLは改行を含んだ長文や折り返し文字列も記述できます。

|（パイプ）: 改行をそのまま保持

notes: |
  このアプリでは以下のことに注意してください。
  - 通信エラーが起きたときは再接続されます。
  - 設定変更後は再起動してください。

>（折りたたみ）: 改行をスペースに変換

description: >
  このアプリは、ユーザーの利便性を
  向上させるために設計されています。

|-（最後の改行を除去）

footer: |-
  これでYAMLの説明は終わりです。

"と\を使って改行なしの長文にする

long_text: "この文章はとても長くて\
  複数行にまたがって書かれていますが\
  改行は一切入りません。"

3.4 コメントを使って読みやすく！

すでに紹介しましたが、YAMLでは行の末尾や単独行に#でコメントを書けます。

api_key: "your-key-here"  # 本番環境では絶対に公開しない！

チーム開発や後から読み返すときに、とても役立ちます。

ここまで学べば、もうあなたもYAMLマスターの第一歩です！
次はいよいよ、「PythonでYAMLファイルを読み書きする方法」に入っていきましょう。

4. PythonでYAMLファイルを読み書きする方法

YAMLファイルの書き方がわかったところで、今度はPythonからYAMLファイルを読み込んだり、書き込んだりする方法を紹介します！
Pythonでは「PyYAML（パイ・ヤムル）」というライブラリを使うのが定番です。

4.1 PyYAMLのインストール

まずは、YAMLを扱えるようにするためのライブラリをインストールしましょう。

pip install PyYAML

これだけで準備OKです！

4.2 YAMLファイルを読み込む（safe_load）

次に、実際のYAMLファイルをPythonで読み込んでみましょう。

import yaml

# YAMLファイルを読み込む
with open("config.yaml", "r", encoding="utf-8") as f:
    data = yaml.safe_load(f)

print(data)

このコードでは、config.yaml というファイルを開いて、その中身を data という変数に辞書として読み込んでいます。
safe_load() は、安全に読み込むための関数で、通常はこちらを使えばOKです！

4.3 読み込んだデータにアクセスする

読み込んだYAMLの内容は、Pythonの辞書やリストとして扱えます。

# config.yaml の中身
app:
  name: あなたのアプリ
  debug: true

print(data["app"]["name"])     # → あなたのアプリ
print(data["app"]["debug"])    # → True

Pythonでよく使うdictの感覚で、サクサクアクセスできますね！

4.4 PythonのデータをYAMLとして保存する（safe_dump）

YAMLファイルをPythonから作成・保存したいときは、こちらの方法を使います。

import yaml

# 保存したいデータ（辞書形式）
data = {
    "app": {
        "name": "あなたのアプリ",
        "version": "1.0",
        "debug": True
    }
}

# YAMLファイルとして書き出す
with open("output.yaml", "w", encoding="utf-8") as f:
    yaml.safe_dump(data, f, allow_unicode=True)

✅ポイント解説

allow_unicode=True をつけると、日本語も文字化けせずに出力されます。
辞書・リストをそのまま書き出せるので、設定ファイルの自動生成にも便利です。

4.5 補足：loadとsafe_loadの違い

yaml.load() も使えますが、これは 信頼できないデータに対して使うと危険です。
そのため、基本的には yaml.safe_load() を使うようにしましょう！

このように、PythonとYAMLを組み合わせれば、柔軟で読みやすい設定ファイルの管理ができるようになります。

5. よくあるミスとエラー対処

YAMLは人間にとって読みやすいフォーマットですが、書き方のルールを少し間違えるとエラーになりやすいという特徴もあります。
ここでは、初心者がつまずきやすいポイントと、その対処法をわかりやすく解説します。

5.1 インデントミス

最も多いミスが、スペースの数の違いによるエラーです。
YAMLでは、インデント（字下げ）に半角スペースを使うのがルールです。タブキー（Tab）を使うとエラーになります！

❌ ダメな例（タブとスペースが混ざっている）:

app:
    name: あなたのアプリ  # ← スペース4つ
	version: 1.0         # ← タブ1つ → エラー！

✅ 正しい例（スペースのみでインデント）:

app:
  name: あなたのアプリ
  version: 1.0

エディタで「インデントをスペースに統一」する設定にしておくと安心です！

5.2 クォートの忘れ・必要以上の使用

基本的にYAMLではクォート（"や'）は不要ですが、以下のようなケースでは明示的に囲む方が安全です。

password: "123456"  # 数値扱いにならないようにクォートする
enabled: "no"       # true/falseに誤認識されないように

yesやno、onやoffなどの言葉も、YAMLでは真偽値と判断されるため注意しましょう。

5.3 safe_load vs load の使い分け

yaml.load(f)  # 危険なコードを実行される可能性あり
yaml.safe_load(f)  # 安全に読み込みたいときはこちら

yaml.load() は便利ですが、信頼できないYAMLファイルを読み込むとセキュリティリスクが生じることがあります。
基本的には safe_load() を使いましょう！

5.4 Unicodeエラー（文字化け）

日本語を含むYAMLファイルを扱うときは、文字コードの指定を忘れずに！

with open("config.yaml", "r", encoding="utf-8") as f:

さらに、書き出し時には allow_unicode=True を指定すると、日本語がきれいに保存されます。

5.5 コメントの位置

コメントは # を使えば書けますが、値の中に書いてしまうとエラーになります。

❌ 間違った例：

name: あなたのアプリ #コメント ← 正しそうに見えて、値の一部になることがある

✅ 正しい例：

# アプリの名前を設定
name: "あなたのアプリ"  # ← クォートで明示すれば安全

こうしたポイントを押さえておくことで、YAMLによる設定ファイルのエラーを未然に防ぐことができます。
次は記事のまとめに進みましょう！

6. まとめ｜YAMLを使えば設定ファイルの管理がラクになる！

今回は、PythonでYAMLファイルを扱う方法を初心者向けにやさしく解説してきました。

YAMLは、見た目もスッキリしていて、Pythonの辞書やリストに似ているので、Pythonユーザーとの相性がとても良いフォーマットです。
特に「設定ファイル」として使えば、プログラムの動作を外部からコントロールできて、環境ごとの切り替えやデプロイがとてもスムーズになります。

🔑 今回のポイントをおさらい！

YAMLはキー: 値で書けるシンプルな構造
ネストやリストもスペースやハイフンでわかりやすく記述可能
PythonではPyYAMLライブラリを使って簡単に読み書きできる
safe_load()とsafe_dump()を使えば、安全かつ快適にデータを扱える
コメントや複数行文字列、マージ構文など、便利な機能も豊富！

YAMLを使いこなせるようになれば、あなたのアプリの設定や構成管理が格段に効率化されます。
今後、Flask、Django、FastAPIなどのフレームワークでも、YAML形式での設定ファイルを目にする機会が増えていくはずです。

最初は少し戸惑うかもしれませんが、この記事を何度か読み返して、ぜひ自分のプロジェクトでも活用してみてくださいね 😊

よくある質問（Q&A）

Q YAMLとJSON、どちらを使えばいいの？

用途によって使い分けましょう！

JSON：システム間のデータ通信（APIレスポンスなど）に向いています。マシンにとって扱いやすい形式。
YAML：設定ファイルや構成定義など、人が手で編集する用途に適しています。読みやすさ重視。

Pythonではどちらも扱えますが、設定ファイルにはYAML、通信にはJSONが一般的です。

Q YAMLファイルを読み込むとエラーが出ます。何が原因？

インデントや記述ミスが多いです！

よくある原因は以下の通り：

タブ（Tab）ではなく半角スペースでインデントする必要がある
: のあとにスペースがない
リストの書き方（-）が間違っている
クォートで囲むべき文字列（例: yes や 1234）を囲んでいない

エディタにYAML構文チェッカーを入れるとミスに気づきやすくなります！

Q safe_loadとloadの違いはなんですか？

safe_loadは安全な読み込み用、loadは高機能だけど危険な場合も。

safe_load() → 標準的なYAMLデータを安全に読み込む（おすすめ）
load() → Pythonオブジェクトも読み込めるが、信頼できないファイルでは使わないで！

普段は safe_load() を使えばOKです。