Pythonプログラミングの世界

【初心者向け】PythonでYAMLファイルを安全に読み込む方法｜safe_loadの使い方とエラー対策まで徹底解説

Python実践ガイド
佐川 直弘 | Naohiro Sagawa
By 佐川 直弘 | Naohiro Sagawa (運営者)
※記事内に広告を含みます。Amazonアソシエイトとして適格販売により収入を得ています。
目次

1. PythonでYAMLを読み込むには？｜この記事の概要と対象読者

PythonでYAMLを扱いたいあなたへ

Pythonでアプリケーションやツールを開発していると、「設定ファイル」や「外部データの管理」にYAML形式を使いたくなる場面が増えてきます。特に、JSONよりも可読性が高く、シンプルな記述が可能なYAMLは、エンジニアやデータサイエンティストの間でも人気の高いデータフォーマットです。

たとえば以下のような用途で、YAMLの読み込みが必要になります：

  • Webアプリやスクリプトの設定ファイルを外部に切り出す
  • Docker ComposeやKubernetesの設定ファイルをPythonで解析したい
  • 機械学習フレームワークのパラメータをYAMLで管理したい

その一方で、「どうやってYAMLファイルを読み込めばいいのか分からない」「エラーが出てうまく読み込めない」といった初学者からの声も多く聞かれます。

本記事で学べること

この記事では、PythonでYAMLファイルを安全かつ確実に読み込む方法を、初心者にもわかりやすく解説していきます。具体的には以下のポイントを押さえます：

  • YAMLファイルの基本構造と特徴
  • Pythonでの読み込み方法（safe_load()の使い方）
  • よくあるエラーとその対処法
  • 複数ドキュメントの読み込みや設定ファイルでの実践例

また、セキュリティ面での注意点や、load()とsafe_load()の違いといった、あまり知られていない情報にも触れます。さらに、最後にはよくある質問（FAQ）も用意していますので、あなたの疑問もきっと解消できるはずです。

対象読者

この記事は、以下のような方を対象にしています：

  • PythonでYAMLを使ってみたい初心者〜中級者
  • 設定ファイルを扱う必要がある開発者
  • PyYAMLの使い方に不安がある方
  • safe_load()やエラー対応について詳しく知りたい方

もしあなたが、今後Pythonでの開発を効率化したいと考えているなら、YAMLの扱い方をマスターすることは大きな一歩になります。

この後のセクションでは、YAMLの概要やPythonでの扱い方を段階的に解説していきます。まずは「YAMLとは何か？」から始めましょう。

2. YAMLとは？｜JSONとの違いと特徴を簡単に比較

YAMLとは何か？

YAML（ヤメル、またはヤムル）は、「YAML Ain’t Markup Language（YAMLはマークアップ言語ではない）」の再帰的な略語で、主に構造化データを人間が読み書きしやすくするために設計されたフォーマットです。PythonやRubyなどのプログラミング言語との相性も良く、設定ファイルやデータ交換の場面で多く使われています。

YAMLはインデントによって階層構造を表現し、シンプルで直感的な記述ができるのが大きな特徴です。

JSONとの違い

YAMLはJSONと似た用途で使われますが、両者にはいくつかの明確な違いがあります。以下に代表的な項目を比較してみましょう。

比較項目YAMLJSON
可読性高い（人間に優しい）中程度（機械に優しい）
コメントの記述可能（# を使用）不可
ファイルサイズ小さくなる傾向（記号が少ない）やや大きめ
データ構造の表現より自由度が高い（複雑な構造もOK）配列・オブジェクトが中心
拡張性高い（独自構造の定義も可能）制限がある
サポート状況一部制限あり幅広くサポートされている

YAMLのメリット

YAMLを使うことには、以下のようなメリットがあります：

  • 直感的な書き方：Pythonのインデントと似ており、構造が把握しやすい
  • コメントが書ける：設定ファイルに補足を加えるのに便利
  • 冗長でない：JSONのような中括弧やダブルクォーテーションが不要
  • 人間に優しい：非エンジニアでも読みやすく、修正しやすい

YAMLが使われる場面

YAMLは以下のようなツールやシステムで利用されることが多いです：

  • Docker Compose（docker-compose.yml）
  • Kubernetesの設定ファイル（PodやServiceの定義）
  • CI/CDツール（GitHub Actions、GitLab CIなど）
  • 機械学習ライブラリ（PyTorch LightningやHydraなど）
  • Webアプリやスクリプトの設定ファイル

つまり、YAMLを扱えるようになることは、現代の開発現場において大きな武器になります。

3. PythonでYAMLを扱う準備｜PyYAMLのインストール

PyYAMLとは？

PythonでYAMLファイルを読み込んだり書き込んだりするには、外部ライブラリの「PyYAML」を使うのが一般的です。PyYAMLは、YAML 1.1仕様に基づいたシンプルかつ高機能なライブラリで、Pythonの標準ライブラリには含まれていないため、別途インストールが必要です。

PyYAMLを使うことで、YAMLファイルをPythonの辞書（dict）やリスト（list）として扱えるようになります。これにより、設定ファイルの読み書きや、構造化データの操作が直感的に行えるようになります。

PyYAMLのインストール方法

PyYAMLのインストールは非常に簡単です。以下のように、pipを使ってコマンドライン（またはターミナル）からインストールできます。

pip install pyyaml

※pipが環境にない場合は、python -m pip install pyyamlとしても問題ありません。

仮想環境の利用をおすすめ

開発環境を分離しておきたい場合は、仮想環境（venvやconda）内でインストールすることをおすすめします。複数のプロジェクトを扱う際に、ライブラリのバージョン管理がしやすくなります。

# 仮想環境の作成
python -m venv venv

# 仮想環境を有効化
# Windowsの場合
venv\Scriptsctivate
# macOS/Linuxの場合
source venv/bin/activate

# PyYAMLをインストール
pip install pyyaml

インストールの確認方法

インストール後に、Pythonの対話モード（REPL）やスクリプトで以下のように記述することで、ライブラリが正しくインポートできるか確認できます。

import yaml
print(yaml.__version__)

エラーが出なければ、PyYAMLは正常にインストールされています。バージョンを確認しておくことで、今後の不具合調査にも役立ちます。

4. 【基本】YAMLファイルをPythonで読み込む方法（safe_loadの使い方）

最も基本的な読み込み方法：safe_load()

PyYAMLを使ってYAMLファイルを読み込む際、最もよく使われる関数が safe_load() です。この関数は、安全にYAMLを読み込むために設計された関数であり、読み込んだデータをPythonの辞書（dict）やリスト（list）として取得することができます。

まずは、基本的なYAMLファイルと、その読み込みコードを見てみましょう。

サンプルYAMLファイル（config.yaml）

app:
  name: SampleApp
  version: 1.0.0
debug: true
servers:
  - host: localhost
    port: 8000
  - host: example.com
    port: 443

このように、ネストされた構造やリストを含むYAMLファイルは、設定ファイルとして非常に使いやすい形式です。

Pythonでの読み込みコード例

以下のコードで、上記のYAMLファイルを読み込むことができます：

import yaml

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

print(config)

出力例（Pythonの辞書形式）

{
  'app': {'name': 'SampleApp', 'version': '1.0.0'},
  'debug': True,
  'servers': [
    {'host': 'localhost', 'port': 8000},
    {'host': 'example.com', 'port': 443}
  ]
}

このように、YAMLファイルはそのままPythonのネイティブなデータ構造として扱えるため、後続の処理にもスムーズに活用できます。

open()関数ではエンコーディング指定が重要

特に日本語が含まれるYAMLファイルを扱う場合、open()関数でencoding='utf-8'を指定することを忘れないようにしましょう。これを省略すると、Windows環境などで文字化けが発生する可能性があります。

ワンポイント：with構文の活用

ファイル読み込み時には、with open(...) as f: のようにwith構文を使うことで、ファイルのクローズ漏れを防ぎ、安全に処理を行うことができます。これはPythonのベストプラクティスとして推奨されている書き方です。

5. safe_loadとloadの違い｜PythonでのYAML読み込みの注意点

safe_load()とload()は何が違うのか？

PyYAMLには、YAMLファイルを読み込むための関数が複数ありますが、最も混乱しやすいのが safe_load() と load() の違いです。

一見すると、どちらもYAMLをPythonのデータとして読み込むための関数ですが、セキュリティ面や機能面に大きな違いがあります。誤って使うと、外部からの悪意あるYAMLファイルでコードを実行される危険性もあるため、理解して正しく使い分けることが重要です。

safe_load()の特徴（安全な読み込み）

import yaml

with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.safe_load(f)
  • 使うべき基本関数
  • 安全性が高い（任意のPythonオブジェクトを読み込まない）
  • 基本的なデータ型（辞書、リスト、文字列、数値など）に制限
  • 未知の型やオブジェクトを読み込もうとするとエラーになる

safe_load()は、その名の通り「安全な読み込み」を行うための関数であり、設定ファイルや外部データを扱う際には、ほとんどのケースでこちらを使うのがベストです。

load()の特徴（柔軟だがリスクあり）

import yaml

with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.load(f, Loader=yaml.FullLoader)
  • より柔軟にYAMLを解釈できる
  • Pythonオブジェクト（例：関数、クラスインスタンスなど）を復元可能
  • セキュリティ上のリスクがあるため、Loaderの指定が必須

実は、昔のPyYAMLではload()を単独で使うことができましたが、現在ではLoaderの明示指定が求められています。何も指定せずに使うと、以下のような警告やエラーが発生します：

yaml.YAMLLoadWarning: calling yaml.load() without Loader=... is deprecated

これは、load()が過去に任意のPythonオブジェクトを実行可能にしてしまう脆弱性を含んでいたためです。つまり、不正なYAMLファイルを読み込むと、Pythonコードを意図せず実行させられるリスクがあるのです。

Loaderの種類（セキュリティと柔軟性の違い）

Loader名特徴推奨度
SafeLoader基本的な型のみ読み込み（安全）◎
FullLoaderより多くのPython型を許容（セキュリティ注意）○
UnsafeLoader任意オブジェクトの読み込みを許容（危険）×

結論：通常はsafe_load()を使おう

もしあなたがYAMLファイルを設定ファイルや外部データとして読み込むだけであれば、safe_load()で十分ですし、むしろそれを使うべきです。load()は特殊な用途（たとえば、自作のPythonオブジェクトをデシリアライズしたい場合など）に限って使用しましょう。

6. よくあるエラーとその解決法｜Python YAML読み込みの落とし穴

YAMLの読み込みでつまずく理由とは？

YAMLは非常にシンプルで読みやすいフォーマットですが、その分、細かい構文ルールに厳格です。特にPythonで読み込む場合、初心者が見落としやすいポイントがいくつかあります。

このセクションでは、PythonでYAMLファイルを読み込む際によくあるエラーとその原因、解決方法を具体的に紹介していきます。

1. インデントのミスによる構文エラー

YAMLではインデントが構造を示す重要な要素です。スペースやタブの不一致があると、読み込み時にエラーになります。

例：インデントエラーのあるYAML

user:
  name: Alice
    age: 30

エラーメッセージ例：

yaml.scanner.ScannerError: mapping values are not allowed here

解決法：

  • インデントはスペース2〜4つで統一（タブは使わない）
  • 子要素は親要素より深くインデントする

2. ファイルのエンコーディングが原因で文字化け

YAMLファイルに日本語などの非ASCII文字が含まれている場合、エンコーディングを適切に指定しないと、文字化けやデコードエラーが発生します。

エラー例：

UnicodeDecodeError: 'cp932' codec can't decode byte...

解決法：

with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.safe_load(f)
  • 明示的に encoding='utf-8' を指定することで解消できます
  • Windows環境では特に忘れやすいポイントです

3. ファイルパスの間違い／存在しないファイル

単純なミスですが、指定したYAMLファイルが存在しないと、FileNotFoundError が発生します。

エラー例：

FileNotFoundError: [Errno 2] No such file or directory: 'config.yaml'

解決法：

  • パスを絶対パスまたは正しい相対パスで指定しているか確認
  • ファイル名や拡張子の打ち間違いがないかチェック
  • ファイルがスクリプトと同じディレクトリにあるか確認

4. safe_loadで読み込んだ結果がNoneになる

これはYAMLの構文自体が正しくても、ファイルの中身が空、あるいはコメントだけの場合に起こる現象です。

例：

# このファイルには何も設定されていません

結果：

data = yaml.safe_load(f)
print(data)  # 出力: None

解決法：

  • ファイルの中に有効なYAMLデータが記述されているか確認
  • コメントだけ、または空白だけではNoneが返されるのは正常な挙動

5. 複雑すぎるYAML構造のパースエラー

大規模で入れ子の深いYAMLファイルでは、構文ミスやアンカー/エイリアスの使い方を誤ってエラーが出ることもあります。

解決法：

  • 段階的に構文を確認（小さなセクション単位で検証）
  • yaml.YAMLError で例外をキャッチして詳細なメッセージを確認するのがおすすめ
try:
    with open('config.yaml', 'r', encoding='utf-8') as f:
        data = yaml.safe_load(f)
except yaml.YAMLError as e:
    print(f"YAML読み込みエラー: {e}")

まとめ：エラーが出たら慌てずに構文と環境をチェック

YAMLは書き方に少し気をつければ非常に扱いやすいフォーマットです。エラーが出た場合は、以下のポイントをチェックしてみましょう：

  • インデントが正しいか（タブを使っていないか）
  • ファイルのエンコーディングはUTF-8か
  • ファイルが存在しているか
  • YAMLの中身が正しく記述されているか

7. 応用：複数ドキュメントのYAMLファイルを読み込む方法（safe_load_all）

YAMLは1つのファイルに複数のドキュメントを含められる

YAMLの大きな特徴のひとつに、1つのファイルの中に複数のデータブロック（ドキュメント）を定義できるという点があります。これにより、設定や構成を分割しつつ、1ファイルでまとめて管理することが可能になります。

ドキュメント同士は、---（3本のハイフン）で区切ることで明示的に分離されます。

複数ドキュメントのYAMLファイル例（multi.yaml）

# サーバー設定1
---
server:
  host: localhost
  port: 8080

# サーバー設定2
---
server:
  host: example.com
  port: 443

このように書かれたYAMLファイルは、2つの独立したデータブロックを持っており、それぞれを個別に読み込む必要があります。

yaml.safe_load_all()の使い方

PyYAMLでは、複数ドキュメントを読み込むために safe_load_all() 関数が用意されています。これは、ファイル内のすべてのYAMLドキュメントをイテレータ（反復可能オブジェクト）として返す関数です。

import yaml

with open('multi.yaml', 'r', encoding='utf-8') as f:
    documents = yaml.safe_load_all(f)
    for doc in documents:
        print(doc)

実行結果（出力例）：

{'server': {'host': 'localhost', 'port': 8080}}
{'server': {'host': 'example.com', 'port': 443}}

このように、各ドキュメントが1つずつ辞書として取得でき、ループで処理することで柔軟に活用できます。

safe_load()との違いに注意

通常の safe_load() は最初の1つのドキュメントしか読み込まないため、複数ドキュメントに対応したファイルには適していません。

関数名対応するYAML形式戻り値の形式
safe_load()単一ドキュメントのみデータ（辞書やリストなど）
safe_load_all()複数ドキュメントに対応イテレータ（ループ処理）

読み込んだドキュメントをリストに変換することも可能

場合によっては、すべてのドキュメントをリストとしてまとめて取得したいこともあるでしょう。その場合は、以下のように list() を使えばOKです。

with open('multi.yaml', 'r', encoding='utf-8') as f:
    documents = list(yaml.safe_load_all(f))

これにより、リスト形式で一括処理したり、インデックス指定でアクセスしたりすることが可能になります。

注意点：すべてのYAMLファイルが複数ドキュメント対応ではない

--- で区切られていないYAMLファイルに対して safe_load_all() を使っても問題はありませんが、結果は1つのドキュメントのみになります。つまり、safe_load_all()は万能だが、複数ドキュメントでなければsafe_load()と同じ挙動になることを覚えておきましょう。

8. 【補足】設定ファイルとしてYAMLを使う場合のポイント

なぜYAMLは設定ファイルに向いているのか？

YAMLは、人間が読み書きしやすい構文と、ネストされた構造の柔軟な表現力を兼ね備えているため、多くのプロジェクトで「設定ファイル」として採用されています。特にPythonで開発されるアプリケーションやツールにおいては、YAMLを使うことで設定の見通しが良くなり、保守性も向上します。

以下のような用途において、YAMLはとても重宝されます：

  • Webアプリケーションの環境設定（本番／開発／テスト）
  • 機械学習のハイパーパラメータ設定
  • スクリプトの挙動切り替え
  • APIキーなどの外部依存情報の管理（※機密情報の管理には注意）

実用的なYAML設定ファイルの例

app:
  name: MyApp
  mode: production

logging:
  level: INFO
  file: logs/app.log

database:
  host: localhost
  port: 5432
  user: admin
  password: secret

このように、構成要素をセクションごとにまとめることで、誰が見ても一目で構造がわかる設定ファイルになります。JSONと違い、コメントを自由に書ける点も実務では非常に重要です。

ネスト構造を活かした設定の階層化

YAMLではインデントで階層を表現するため、複雑な設定も直感的に表現できます。たとえば、環境ごとに設定を分けたいときも以下のようにまとめることが可能です：

env:
  dev:
    db: dev-db.local
    debug: true
  prod:
    db: prod-db.server
    debug: false

Python側でこの設定を読み込めば、環境変数などによって自動的に適切な設定を選択できます。

コメントで意図を明示できる

YAMLでは # を使ってコメントを書くことができます。これにより、「なぜその設定になっているのか」「どういったときに変更すべきか」といった情報を設定ファイル内に直接記述できるという大きな利点があります。

# アプリのモード設定（dev, test, production のいずれか）
mode: production

JSONではコメントが書けないため、こういった補足ができないという制限があります。

実行時にYAMLを読み込むコード例（応用）

以下は、Pythonスクリプト側でYAML設定を読み込み、アプリに適用する例です：

import yaml

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

app_name = config['app']['name']
mode = config['app']['mode']
db_host = config['database']['host']

このように、YAMLファイルをPythonの辞書として扱うことで、コードの中に設定値をベタ書きすることなく管理できるようになります。

注意点：機密情報の取り扱いには十分注意を

YAMLは人間にとって扱いやすい反面、平文で保存される形式でもあります。そのため、APIキーやパスワードなどの機密情報をYAMLファイルに記述する際は、以下のような対策が必要です：

  • .gitignoreでリポジトリへのコミットを防ぐ
  • .envファイルなどと組み合わせてYAMLからは参照だけにする
  • 暗号化やアクセス制限を適用する

9. よくある質問（FAQ）

このセクションでは、PythonでYAMLファイルを読み込む際によく寄せられる疑問や、初心者がつまずきやすいポイントをQ&A形式で解説します。実際にプロジェクトで使う際にも役立つ内容ですので、ぜひチェックしてみてください。

Q1. YAMLとJSON、Pythonで扱いやすいのはどっちですか？

A. YAMLは可読性が高く、設定ファイルとして使うには非常に便利です。

PythonではJSONも標準ライブラリでサポートされていますが、YAMLはコメントが書ける、構造が見やすいなどの理由から、設定ファイル用途ではYAMLの方が扱いやすいと感じる人が多いです。ただし、処理速度やデータ交換の互換性が重視される場面では、JSONが好まれることもあります。

Q2. yaml.load()は使ってはいけないのですか？

A. 原則として safe_load() を使うのが安全です。

load() は柔軟性が高い一方で、任意のPythonオブジェクトを復元できてしまうため、セキュリティリスクがあります。 悪意のあるYAMLファイルを読み込むと、意図しないコードが実行される恐れがあるため、基本的には safe_load() を使うのが推奨されます。

もし load() を使う必要がある場合は、Loader=yaml.FullLoader のように明示的に指定し、安全性を意識した実装にしましょう。

Q3. 読み込んだYAMLの中身が空っぽ（None）になるのはなぜ？

A. YAMLファイルが空、またはコメントのみの場合に発生する正常な動作です。

# このファイルはまだ設定されていません

上記のようなファイルを読み込むと、safe_load() の戻り値は None になります。これは異常ではなく、YAMLとして有効な「空データ」です。ファイルの中身が正しく記述されているかを確認しましょう。

Q4. YAMLファイルの中で値を再利用（変数のように）できますか？

A. YAMLには「アンカー」と「エイリアス」という仕組みがあります。

default: &defaults
  timeout: 30
  retries: 3

service1:
  <<: *defaults
  host: service1.local

service2:
  <<: *defaults
  host: service2.local

このように、& でアンカー（定義）、* でエイリアス（参照）を記述することで、同じ設定を複数箇所で使い回すことが可能です。ただし、PyYAMLではこの構文を使う際に特定のバージョンやLoader設定が必要になる場合があるため、事前に動作確認をしましょう。

Q5. Windows環境で日本語が文字化けします。どうすればいいですか？

A. ファイルの読み込み時にエンコーディングを明示することで解決します。

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

Windowsのデフォルト文字コード（cp932）では、UTF-8で書かれたYAMLファイルを正しく読み込めないことがあります。必ず encoding='utf-8' を明示しましょう。

Q6. YAMLファイルを複数の設定ブロックに分けて書いた場合はどう読み込めばいい？

A. safe_load_all() を使うことで、複数のドキュメントを読み込めます。

---
app: App1
port: 3000
---
app: App2
port: 4000

このようなファイルは yaml.safe_load_all() で1つずつ処理できます：

with open('multi.yaml', 'r', encoding='utf-8') as f:
    for doc in yaml.safe_load_all(f):
        print(doc)

10. まとめ｜PythonでのYAML読み込みをマスターしよう

YAML読み込みの基本から応用までを振り返る

本記事では、「PythonでYAMLファイルを読み込みたい」という方に向けて、基本的な使い方から、よくあるエラー対処法、複数ドキュメントや設定ファイルとしての応用例まで、段階的に解説してきました。

改めて、記事のポイントをまとめます：

  • PyYAMLのインストール：PythonでYAMLを扱うには、まず pip install pyyaml が必要。
  • 基本の読み込み：yaml.safe_load() を使えば、安全かつ簡単にYAMLを辞書やリストとして読み込める。
  • エラー対策：インデントやエンコーディングミスはよくあるトラブル。構文チェックとencoding='utf-8'が重要。
  • load()との違い：安全性を重視するなら safe_load() を使うべき。load()は適切なLoader指定が必須。
  • 複数ドキュメント対応：safe_load_all()を使えば、1ファイル内の複数設定ブロックも柔軟に処理可能。
  • 設定ファイルとしての実用性：可読性・柔軟性に優れたYAMLは、Pythonプロジェクトでの設定管理に最適。

今後のステップ：YAMLをもっと活用しよう

YAMLの読み込み方法を習得できた今、次は以下のようなステップに進むことで、実務でもさらに活用できるようになります：

  • YAMLファイルへの書き込み：yaml.dump() を使った設定ファイルの自動生成
  • JSONとの相互変換：Web APIや外部サービスと連携する際に便利
  • .envファイルや環境変数との併用：安全性の高い設定管理手法の構築
  • 設定の自動ロード化：アプリ起動時に環境に応じた設定ファイルを動的に読み込む仕組み

これらをマスターすれば、Pythonを使った開発がより柔軟で再利用性の高いものになります。

今後も、現場で役立つPythonのテクニックやツールの使い方をわかりやすく紹介していきます。ぜひブックマークして、繰り返し活用してください。

これで、PythonによるYAMLファイルの読み込みについての解説は完了です。
実務でも使える知識を身につけて、ぜひあなたのプロジェクトにもYAMLを取り入れてみてください。