yamllint完全ガイド：YAMLファイルを完璧にチェック【初心者向け】

Kubernetesの設定ファイルやCI/CDのパイプライン設定を書いていて、「構文エラー」で何時間も悩んだ経験はありませんか？

YAMLはスペースひとつ、インデントひとつ間違えただけで動かなくなる、とてもデリケートな形式です。

そんな悩みを解決してくれるのがyamllintというツールです。今回は、このYAMLファイルの救世主について、初心者の方でも分かりやすく解説していきますよ！

---

yamllintとは？基本を理解しよう

yamllintは、YAMLファイルの構文や書き方をチェックしてくれるツールです。

YAMLって何？

まず、YAMLについて簡単におさらいしましょう。

YAMLは「YAML Ain’t Markup Language」の略で、設定ファイルやデータ記述に使われる形式です。

特徴：

• 人間が読みやすい
• インデント（字下げ）で階層を表現
• 設定ファイルによく使われる

使われている場所：

• Kubernetes（コンテナオーケストレーション）
• Docker Compose
• GitHub Actions、GitLab CI/CD
• Ansible（自動化ツール）
• CircleCI、Travis CI

DevOpsやクラウド開発では避けて通れない形式ですね。

YAMLの落とし穴

インデントが命：

YAMLでは、スペースの数で階層を表します。タブ文字は使えません！

# 正しい例
person:
  name: Taro
  age: 30

# 間違い例（インデントがバラバラ）
person:
  name: Taro
    age: 30

このように、ちょっとしたミスで全体が壊れてしまうんです。

yamllintの役割

問題を事前に発見：

yamllintは、YAMLファイルを実際に使う前に、構文エラーやスタイル違反をチェックしてくれます。

「デプロイして初めてエラーに気づく」という悲劇を防げるんですよ。

---

yamllintで検出できる問題

どんな問題を見つけられるのか見てみましょう。

構文エラー

YAMLの文法違反：

• インデントの不整合
• タブ文字の使用
• 不正な文字
• 閉じていない引用符

これらは実行時にエラーになるので、必ず修正が必要です。

スタイル違反

ベストプラクティスからの逸脱：

• 行末の空白
• 空行の数
• コメントのインデント
• キーの重複
• 長すぎる行

これらは実行できるかもしれませんが、可読性や保守性のために修正すべき項目ですね。

実例：よくあるエラー

エラー1：タブ文字の混入

services:
    web:  # ← タブ文字が入っている
      image: nginx

yamllintの警告：

./docker-compose.yml
  2:1       error    found character '\t' that cannot start any token  (syntax)

エラー2：インデントの不一致

person:
  name: Taro
   age: 30  # ← 3スペース（他は2スペース）

yamllintの警告：

./config.yml
  3:4       error    wrong indentation: expected 2 but found 3  (indentation)

---

インストール方法

各環境でのインストール手順を紹介します。

Pythonのpipでインストール（推奨）

yamllintはPythonで書かれているので、pipでインストールできます。

前提条件：

Python 3.6以降がインストールされていること

インストール：

# システム全体にインストール
pip install yamllint

# ユーザーディレクトリにインストール（推奨）
pip install --user yamllint

# 特定のバージョンをインストール
pip install yamllint==1.33.0

確認：

yamllint --version

Ubuntu/Debianの場合

# APTでインストール
sudo apt update
sudo apt install yamllint

macOSの場合

Homebrewを使用：

brew install yamllint

Windowsの場合

方法1：pipを使用

pip install yamllint

方法2：WSL（Windows Subsystem for Linux）を使用

WSL内でLinux版をインストールするのが便利ですよ。

Dockerで使用

インストール不要で使いたい場合は、Docker版もあります。

docker run --rm -v $(pwd):/data cytopia/yamllint .

---

基本的な使い方

さっそく使ってみましょう。

単一ファイルのチェック

# ファイルをチェック
yamllint config.yaml

問題がない場合：

何も出力されません。

問題がある場合：

./config.yaml
  3:4       error    wrong indentation: expected 2 but found 3  (indentation)
  5:81      warning  line too long (85 > 80 characters)  (line-length)

複数ファイルのチェック

# 複数ファイルを指定
yamllint file1.yaml file2.yml file3.yaml

# ディレクトリ内すべて
yamllint .

# 特定の拡張子のみ
yamllint **/*.yaml

# 再帰的にチェック
yamllint -r /path/to/directory

標準入力からチェック

# パイプで渡す
cat config.yaml | yamllint -

# ヒアドキュメント
yamllint - <<EOF
person:
  name: Taro
  age: 30
EOF

出力形式の指定

デフォルト（人間向け）：

yamllint config.yaml

parsable形式（スクリプト向け）：

yamllint -f parsable config.yaml
# 出力: ./config.yaml:3:4: [error] wrong indentation (indentation)

GitHub Actions形式：

yamllint -f github config.yaml
# 出力: ::error file=config.yaml,line=3,col=4::wrong indentation

colored（色付き）：

yamllint -f colored config.yaml

---

設定ファイルのカスタマイズ

yamllintの動作は、設定ファイルでカスタマイズできます。

設定ファイルの場所

yamllintは、以下の順番で設定ファイルを探します。

1. コマンドラインで指定（-cオプション）
2. .yamllint（カレントディレクトリ）
3. .yamllint.yamlまたは.yamllint.yml
4. $XDG_CONFIG_HOME/yamllint/config
5. ~/.config/yamllint/config

プロジェクトのルートに.yamllintを置くのが一般的ですね。

基本的な設定ファイル

.yamllint の例：

---
extends: default

rules:
  line-length:
    max: 120
  indentation:
    spaces: 2
  comments:
    min-spaces-from-content: 1

プリセット設定

relaxed（緩い）：

extends: relaxed

スタイル違反をほとんど無視して、構文エラーのみチェックします。

default（デフォルト）：

extends: default

バランスの取れた設定で、多くのプロジェクトに適しています。

主要なルール設定

インデント設定：

rules:
  indentation:
    spaces: 2  # スペースの数
    indent-sequences: true  # リストのインデント
    check-multi-line-strings: false

行の長さ：

rules:
  line-length:
    max: 120  # 最大文字数
    level: warning  # errorまたはwarning

空行の制御：

rules:
  empty-lines:
    max: 2  # 連続する空行の最大数
    max-start: 0  # ファイル先頭の空行
    max-end: 1  # ファイル末尾の空行

末尾の空白：

rules:
  trailing-spaces: enable

キーの重複チェック：

rules:
  key-duplicates: enable

コメントのスタイル：

rules:
  comments:
    require-starting-space: true
    min-spaces-from-content: 2

ルールの無効化

特定のルールを無効にする：

rules:
  line-length: disable
  trailing-spaces: disable

プロジェクト全体で無効化：

extends: default

rules:
  document-start: disable  # ドキュメント開始の --- を不要に

---

特定の行や範囲を無視する

コメントで、yamllintの警告を抑制できます。

1行だけ無視

person:
  name: Taro
  very-long-key-name-that-exceeds-line-limit: value  # yamllint disable-line rule:line-length

複数行を無視

# yamllint disable rule:line-length
some:
  very:
    long:
      nested:
        structure:
          that:
            exceeds: limit
# yamllint enable rule:line-length

すべてのルールを無視

# yamllint disable
# この範囲はチェックされない
# yamllint enable

ファイル全体を無視

.yamllint 設定ファイル：

ignore: |
  /vendor/
  /node_modules/
  *.min.yaml

または、コマンドラインで指定：

yamllint --ignore 'vendor/*' .

---

CI/CDパイプラインへの組み込み

yamllintを自動チェックに組み込みましょう。

GitHub Actionsでの使用

.github/workflows/lint.yml：

name: Lint YAML files

on: [push, pull_request]

jobs:
  yamllint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'

      - name: Install yamllint
        run: pip install yamllint

      - name: Lint YAML files
        run: yamllint .

GitLab CI/CDでの使用

.gitlab-ci.yml：

yamllint:
  image: python:3.11
  stage: test
  before_script:
    - pip install yamllint
  script:
    - yamllint .

CircleCIでの使用

.circleci/config.yml：

version: 2.1

jobs:
  lint:
    docker:
      - image: cimg/python:3.11
    steps:
      - checkout
      - run:
          name: Install yamllint
          command: pip install yamllint
      - run:
          name: Lint YAML
          command: yamllint .

workflows:
  version: 2
  build:
    jobs:
      - lint

pre-commitフックでの使用

コミット前に自動チェック：

.pre-commit-config.yaml：

repos:
  - repo: https://github.com/adrienverge/yamllint
    rev: v1.33.0
    hooks:
      - id: yamllint
        args: [--strict]

インストールと有効化：

# pre-commitをインストール
pip install pre-commit

# フックを有効化
pre-commit install

# 手動実行
pre-commit run --all-files

これで、コミット時に自動的にyamllintが実行されますよ。

---

エディタとの統合

エディタでリアルタイムにチェックできると便利です。

Visual Studio Code

拡張機能：

「YAML」拡張機能（Red Hat製）がおすすめです。

1. 拡張機能マーケットプレイスで「YAML」を検索
2. インストール
3. yamllintがインストールされていれば、自動的に統合される

settings.json：

{
  "yaml.validate": true,
  "yaml.format.enable": true,
  "yaml.customTags": []
}

Vim/Neovim

ALE（Asynchronous Lint Engine）を使用：

" .vimrc または init.vim
Plug 'dense-analysis/ale'

let g:ale_linters = {
\   'yaml': ['yamllint'],
\}
let g:ale_fixers = {
\   'yaml': ['prettier'],
\}

Emacs

flycheck を使用：

(use-package flycheck
  :ensure t
  :init (global-flycheck-mode))

(require 'flycheck-yamllint)
(add-hook 'yaml-mode-hook 'flycheck-mode)

Sublime Text

SublimeLinter と SublimeLinter-yamllint：

1. Package Controlで「SublimeLinter」をインストール
2. 「SublimeLinter-yamllint」をインストール
3. yamllintが自動的に使われる

---

実用的な設定例

プロジェクトタイプ別の推奨設定です。

Kubernetes/Helm向け設定

.yamllint：

extends: default

rules:
  line-length:
    max: 120
    level: warning
  indentation:
    spaces: 2
  document-start: disable
  truthy:
    allowed-values: ['true', 'false', 'yes', 'no']
  comments-indentation: disable  # Helmテンプレートで誤検出を防ぐ

ignore: |
  charts/
  .helmignore

Ansible向け設定

.yamllint：

extends: default

rules:
  line-length:
    max: 160
  indentation:
    spaces: 2
    indent-sequences: consistent
  truthy:
    allowed-values: ['true', 'false', 'yes', 'no']
  comments:
    min-spaces-from-content: 1

ignore: |
  .ansible/
  roles/*/tests/

CI/CD設定向け

.yamllint：

extends: default

rules:
  line-length:
    max: 100
  indentation:
    spaces: 2
  document-start: disable
  truthy: disable  # on/offを許可

ignore: |
  .github/workflows/external/

緩い設定（レガシープロジェクト）

.yamllint：

extends: relaxed

rules:
  line-length: disable
  trailing-spaces: enable
  key-duplicates: enable

---

トラブルシューティング

よくある問題と解決方法です。

問題1：「No such file or directory」エラー

症状：

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

原因：

ファイルパスが間違っているか、ファイルが存在しません。

対処法：

# ファイルの存在確認
ls -la config.yaml

# 正しいパスを指定
yamllint ./path/to/config.yaml

問題2：タブ文字のエラーが大量に出る

症状：

found character '\t' that cannot start any token

原因：

エディタがタブ文字を挿入しています。

対処法：

エディタでタブをスペースに変換：

VS Codeの場合：

{
  "editor.insertSpaces": true,
  "editor.tabSize": 2
}

既存のタブを変換：

# タブをスペースに変換（2スペース）
expand -t 2 config.yaml > config_fixed.yaml

# 上書き保存
expand -t 2 config.yaml | sponge config.yaml

問題3：Helmテンプレートで誤検出

症状：

Helmテンプレート（{{ }} を含むYAML）で大量のエラーが出る。

対処法：

Helmテンプレートファイルは、yamllintでチェックすべきではありません。

# .yamllint
ignore: |
  templates/
  **/templates/**

または、helm lint コマンドを使いましょう。

問題4：「command not found」

症状：

yamllint: command not found

原因：

PATHが通っていないか、インストールされていません。

対処法：

# pipでユーザーインストールした場合
export PATH="$HOME/.local/bin:$PATH"

# .bashrc または .zshrc に追加
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 再インストール
pip install --user yamllint

---

他のツールとの比較

類似ツールとの違いを見てみましょう。

yamllint vs yamlvalidator

項目	yamllint	yamlvalidator
チェック内容	構文＋スタイル	構文のみ
カスタマイズ性	高い	低い
実装言語	Python	Go
速度	中程度	高速

使い分け：

• スタイルも含めてチェックしたい → yamllint
• 構文チェックだけ高速に → yamlvalidator

yamllint vs JSON Schema

JSON Schema：

YAMLの構造や値の妥当性を検証できます。

# schema.json で構造を定義
# ajvなどのツールで検証

使い分け：

• 構文とスタイル → yamllint
• データの妥当性（型、必須項目など） → JSON Schema

両方を組み合わせることで、完全なチェックができますよ。

yamllint vs prettier

Prettier：

コードフォーマッターで、YAMLも整形できます。

prettier --write "**/*.yaml"

使い分け：

• チェックだけ → yamllint
• 自動修正も → prettier
• 両方使う → yamllint でチェック、prettier で修正

---

高度な使い方

より深い活用方法を紹介します。

カスタムルールの作成

yamllintのルールは、Pythonで拡張できます。

例：独自のルールを作成

# custom_rules.py
from yamllint.linter import LintProblem

def custom_check(conf, token, prev, next, nextnext, context):
    if token.value.startswith('TODO'):
        yield LintProblem(token.start_mark.line + 1,
                          token.start_mark.column + 1,
                          "Found TODO comment")

# yamllintプラグインとして登録

統計情報の出力

# エラーと警告の数を表示
yamllint . | grep -c error
yamllint . | grep -c warning

# ファイルごとの問題数
for file in *.yaml; do
  count=$(yamllint "$file" 2>&1 | wc -l)
  echo "$file: $count issues"
done

大規模プロジェクトでの並列実行

# GNU Parallelを使用
find . -name '*.yaml' | parallel -j 4 yamllint

# xargsを使用
find . -name '*.yaml' -print0 | xargs -0 -P 4 -I {} yamllint {}

継続的な改善

段階的にルールを厳しくする：

# ステップ1: まず構文エラーだけ修正
extends: relaxed

# ステップ2: インデントを統一
rules:
  indentation: enable

# ステップ3: 行の長さを制限
rules:
  line-length:
    max: 120

# ステップ4: すべてのルールを有効化
extends: default

---

よくある質問

Q: yamllintは無料で使える？

A: はい、完全に無料でオープンソースです。MITライセンスなので、商用利用も問題ありません。個人でも企業でも自由に使えますよ。

Q: JSONファイルもチェックできる？

A: いいえ、yamllintはYAML専用です。JSONには「jsonlint」など、専用のツールを使いましょう。ただし、YAMLはJSONの上位互換なので、有効なJSONは有効なYAMLでもあります。

Q: 自動修正機能はある？

A: 残念ながら、yamllint自体には自動修正機能がありません。チェックのみを行います。自動修正が必要な場合は、prettierなどのフォーマッターと組み合わせて使うのがおすすめですね。

Q: Windows環境でうまく動かない

A: Pythonのパス設定を確認してください。特にpip install --userでインストールした場合、%APPDATA%\Python\ScriptsにPATHを通す必要があります。または、WSLを使うと楽ですよ。

Q: 大量のファイルをチェックすると遅い

A: 並列実行や、変更されたファイルだけチェックする方法を検討しましょう。git diffと組み合わせると効率的です。

# 変更されたファイルのみチェック
git diff --name-only --diff-filter=ACM "*.yaml" "*.yml" | xargs yamllint

---

まとめ：yamllintでYAMLを完璧に

yamllintについて、重要なポイントをおさらいします。

今日学んだこと：

• yamllintはYAMLファイルの構文とスタイルをチェックするツール
• pipで簡単にインストールできる
• 構文エラーとスタイル違反の両方を検出
• .yamllint設定ファイルでカスタマイズ可能
• CI/CDパイプラインに組み込める
• エディタと統合してリアルタイムチェック
• pre-commitフックで自動チェック
• プロジェクトに応じた設定が重要

yamllintは、YAML初心者からベテランまで、すべての人に役立つツールです。

特にKubernetesやCI/CDパイプラインを扱う方には必須と言えるでしょう。「デプロイしてエラー」を防ぎ、チーム全体のコード品質を向上させられます。

最初は警告が大量に出て驚くかもしれませんが、一つずつ修正していけば、きれいで保守しやすいYAMLファイルが書けるようになりますよ。ぜひ今日からyamllintを導入して、快適なYAMLライフを送ってくださいね！

---

関連記事：

• YAMLの基本文法を学ぶ
• Kubernetesマニフェストのベストプラクティス
• CI/CDパイプラインの構築方法