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形式での設定ファイルを目にする機会が増えていくはずです。

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

あわせて読みたい｜YAMLと相性のいいPython活用記事

YAMLは設定ファイルとしてよく使われますが、それ以外にもファイル形式や構成管理、データ操作といったテーマとも関係が深いです。以下の記事もあわせて読むことで、より理解が深まりますよ！

🔗 Pythonの設定ファイル・データ形式に関する記事

• ✅ 【Python入門】jsonモジュールの使い方とJSONの基本
  　JSONとYAMLの違いを理解したいなら、こちらも読んでおくと安心です！

🔗 Pythonのファイル操作や自動化に関する記事

• ✅ 【Python入門】デスクトップアプリ開発入門｜PySimpleGUIでGUI作成
  　GUIアプリの設定ファイルとしてYAMLを使う場面にも活かせます！
• ✅ 【Python入門】Pandasの使い方完全ガイド｜DataFrame操作と分析の基本
  　データの扱いに慣れてきたら、次はPandasでの表形式データ分析にも挑戦してみましょう！
• ✅ 【Python入門】Pythonで日付計算・カレンダー操作を簡単に！relativedeltaとcalendarの使い方ガイド
  　YAMLに日時設定を書く際に知っておくと便利な、日付の扱い方はこちら。

よくある質問（Q&A）