2024.12.25 アーキテクチャ

PlantUMLとは？記法・使い方・インストールから.puml拡張子まで解説

PlantUML（プラントユーエムエル）は、テキストを書くだけでUML図を生成するオープンソースのツールです。マウスで図形を並べる作図と違い、@startuml から @enduml までの数行でシーケンス図やクラス図が出力される仕組みです。図の実体がテキストなので、Gitで差分が読め、プルリクエストのレビュー対象にできます。この記事では、記法の型と図種別ごとの書き方、インストールとJava要件、.puml拡張子とファイル分割、CLIやサーバ描画による自動生成、ライセンス選択、Mermaidとの違いまでを、公式ドキュメントの記述（2026年8月時点）に沿って整理します。

まとめ：PlantUMLの要点と採用判断の結論

PlantUMLはテキスト記述からUML図を生成するOSSです。読み方は「プラントユーエムエル」。公式のダウンロードページによれば、2026年8月時点の版は v1.2026.6 系で、「メジャー番号・リリース年・その年の連番」という並びで採番されています。

記述は @startuml と @enduml で囲み、要素と関係を1行ずつ書く形式です。1ファイルに複数のブロックを置けば、ブロック単位で別々の画像として出力されます。ファイルの拡張子は .puml が標準で、VS Code拡張は .wsd／.pu／.puml／.plantuml／.iuml の5つをPlantUMLの言語として扱います。

ローカル描画にはJavaが要ります。公式のクイックスタートは最低推奨をJava 11としており、移行できない環境向けにJava 8対応の別ビルドが配布されています。Graphvizは全図で必要なわけではありません。ユースケース図・クラス図・オブジェクト図・コンポーネント図・配置図・ステート図・旧記法のアクティビティ図がノード配置にGraphvizを使い、シーケンス図はそれを使わずに描かれます。

Javaを端末に入れたくない場合は、公式のPlantUML Server、Dockerイメージ、Krokiのような描画サービスに逃がせます。レイアウトエンジンについても、!pragma layout smetana を指定すればPlantUMLに同梱されたJava移植版が使われ、外部のdotプロセスを起動せずに描画できます。

ライセンスは1本ではなく、GPLv3・GPLv2・LGPL・Apache 2.0・BSD・EPL 2.0・MITから選んで入手する形です。商用利用は可能です。ただし同梱される機能に差があり、ditaa連携はGPL系とLGPL、ELKレイアウトはEPL版にだけ入ります。GraphvizをバンドルしないビルドがほしいならLGPL版を選びます。

採用判断は単純です。設計図をコードと同じリポジトリに置き、変更のたびに差分でレビューしたいならPlantUMLが噛み合います。逆に、図の見た目を1ピクセル単位で作り込みたい提案資料や、UMLをほとんど使わない現場では、GUI作図ツールのほうが早く終わります。

PlantUMLとは何か・.puml形式のテキスト作図が設計に効く理由

PlantUMLは、UML（Unified Modeling Language）の図をテキスト記述から生成するツールです。設計や要件定義の内容を、図として出力しつつテキストのまま管理できる点が中心的な性質になります。以下では定義と守備範囲、版番号の読み方までを押さえます。

PlantUMLの定義とモデリングツールではないという位置づけ

PlantUMLは、人が読める短い文からUML図を生成するジェネレータです。公式FAQはこの点をはっきり書いていて、「相互継承のような矛盾した図の作成を妨げない」ため、モデリングツールというよりは作図ツールに近い、と位置づけています。

この一文は導入判断に直結します。厳密なメタモデル検証やコード生成まで求めるなら、Enterprise Architectのような商用モデリングツールの領分です。PlantUMLに任せられるのは、設計意図を素早く図にして共有し、その図をテキストとして版管理する部分に限られます。

.pumlと.wsdなど拡張子の使い分けとファイル分割の基準

標準の拡張子は .puml です。VS Code拡張（qjebbs/vscode-plantuml、2026年8月時点で2.18系）のpackage.jsonを見ると、言語IDが plantuml に対応づけられた拡張子は .wsd・.pu・.puml・.plantuml・.iuml の5つでした。!include で読み込む共通定義ファイルに .iuml を当てて、図の本体と部品を拡張子で見分ける運用がよく使われます。

コマンドラインでディレクトリを丸ごと処理する場合は、対象が拡張子で決まります。公式のコマンドラインページによれば、.txt・.tex・.java・.htm・.html・.c・.h・.cpp・.apt・.pu・.puml・.hpp・.hh・.md の各ファイルから @startXYZ と @endXYZ のブロックが探索されます。ソースコードのコメントやMarkdownに図を埋めたまま出力できるのは、この探索仕様があるためです。

2009年の登場から v1.2026系に至る版番号の読み方と記録

PlantUMLの公開は2009年です。当時の狙いは、設計図を短時間で作って視覚的な意思疎通を回すことにありました。

採番はセマンティックバージョニングの考え方を踏まえつつ、独自の並びになっています。公式ダウンロードページの説明では、先頭がメジャー番号、続く4桁がリリース年、末尾がその年の何本目かを表します。v1.2026.6 なら「メジャー1系・2026年・その年の7本目（0始まり）」という読み方です。バグ報告や再現手順を書くときは、この3つ目の番号まで含めて記録しておくと、後から差分を追えます。

対応する図の種類とUML以外の図まで広がった守備範囲の全体像

UML図としては、シーケンス図・ユースケース図・クラス図・オブジェクト図・アクティビティ図・コンポーネント図・配置図・ステート図・タイミング図に対応します。設計の主要な場面はここでほぼ埋まります。仕様が定める図の全体像と、案件で実際に書く図の絞り込みはUMLの14種類の図と工程別の使い分けで整理しています。

守備範囲はUMLの外にも伸びています。公式サイトのナビゲーションに並ぶだけでも、ガントチャート、マインドマップ、WBS、ネットワーク図、ワイヤーフレーム（Salt）、ArchiMate、EBNF、JSONとYAMLの構造表示があります。UML図のためだけに入れたはずが、スケジュールや構成図まで同じ記法で書けてしまう、というのが実際の使われ方です。

インストールと実行環境の準備・Java 11系とGraphvizの要否

PlantUMLはJava上で動くため、導入の成否はJavaの状態でほぼ決まる仕組みです。加えて、Graphvizが要る図と要らない図の切り分けを最初に理解しておくと、環境構築の手間が減ります。ここでは要件と手順、そしてJavaを入れない選択肢までを順に見ます。

動作要件とJava 11系の推奨理由・Java 8向けの別配布

公式のクイックスタートは、ローカル導入の前提としてJavaの存在確認を挙げ、java -version での確認を案内しています。最低推奨はJava 11で、セキュリティと性能の改善を理由にJava 11以降への移行が促されています。

Java 8から動かせない事情がある環境もあります。その場合はダウンロードページに用意された「Java 8版」のビルドを使います。ただしこれは移行できない場合の逃げ道という扱いなので、恒久運用の前提には置かないでください。踏み台サーバやCIランナーのイメージを更新できるなら、そちらを先に片づけたほうが後が楽になります。

WindowsとmacOS・Linuxでの導入手順と配置の違い

導入そのものはインストーラを伴いません。plantuml.jar を1つ置くだけで動きます。

Windows：公式サイトからplantuml.jarを取得し、任意のフォルダに置いて java -jar plantuml.jar で起動する
macOS：Homebrewで brew install plantuml を実行し、plantuml コマンドとして使う
Linux：ディストリビューションのパッケージ（aptなど）を使うか、jarを直接配置する

Windowsの場合、Graphvizのコンパイル済みバイナリがPlantUML側に同梱されているため、別途の導入は基本的に不要です。macOSとLinuxでは事情が変わり、Graphvizを使う図を描くならパッケージマネージャでdotを入れる作業が残ります。チームでOSが混在しているなら、この差が「自分の端末では出るのに他の人は出ない」の原因になります。

Graphvizが必要な図と不要な図の切り分け基準と実務上の意味

Graphvizは全図で要るわけではありません。公式のSmetana解説には、ノード位置の計算にGraphvizのdotを使う図が明記されています。

図の種類	Graphviz	備考
シーケンス図	不要	内部で座標を決める
クラス図	必要	ノード配置をdotが計算
ユースケース図	必要	同上
オブジェクト図	必要	同上
コンポーネント図	必要	同上
配置図	必要	同上
ステート図	必要	同上
旧記法のアクティビティ図	必要	新記法は扱いが異なる

切り分けの実務的な意味はこうです。シーケンス図しか書かないチームなら、Graphvizの導入で悩む必要がありません。クラス図を1枚でも描く予定があるなら、dotの導入か後述のSmetana指定を最初に決めておきます。

Dockerとサーバ描画で端末にJavaを入れずに済ませる構成

端末にJavaを入れずに済ませる方法は複数あります。公式が案内しているのはDockerです。docker pull plantuml/plantuml-server:jetty でJetty版のサーバイメージを取得し、docker run -d -p 8080:8080 plantuml/plantuml-server:jetty で起動すればブラウザから描画できます。CLI用のイメージはGitHub Packagesにも公開されており、docker run ghcr.io/plantuml/plantuml の形で呼び出せます。

もっと軽く済ませるなら、公式のPlantUML Serverをそのまま使う、あるいはVS Code拡張の描画先をサーバに切り替える方法があります。社外のサーバへ図のテキストを送る形になるため、機密を含む設計図では自社内にサーバを立ててください。この判断を曖昧にしたまま既定のサーバ設定で運用を始めると、後から止めるほうが手間になります。

導入直後に描画まで通ったかを確かめる最小の手順と実行コマンド

導入できたかどうかは、実際に1枚出力してみるのが早道です。@startuml、Alice -> Bob: test、@enduml の3行だけのテキストファイルを作り、java -jar plantuml.jar sequenceDiagram.txt を実行します。同じ場所に sequenceDiagram.png ができていれば、描画までの経路が通っています。

GUIで確かめたいときは java -jar plantuml.jar -gui を実行し、テキストファイルを置いたディレクトリを選ぶ形です。Graphvizの状態だけを確認したい場合は、コマンドラインオプションの --check-graphviz が使えます。まずシーケンス図、次にクラス図の順で試すと、Java側の問題かGraphviz側の問題かを一度に切り分けられます。

記法の基本構造と図種別で共通する4つの記述の型と押さえる順序

PlantUMLの記法は、図の種類ごとにゼロから覚え直すものではありません。囲みの構造、要素の宣言、関係を表す線、補足のノート、という4つの型が共通しており、この型を先に掴むと図種別の差分だけを追えば済みます。

@startumlと@endumlで囲む基本構造と複数図の分割

記述は @startuml で始まり @enduml で終わります。この間に書いた内容が1枚の図になります。囲みを閉じ忘れると図が出力されないため、エラーの原因として最初に疑う箇所です。

1つのファイルに囲みを複数並べれば、ブロックごとに別の画像が生成されます。@startuml diagram1 のように囲みへ名前を与えると、出力ファイル名にその名前が使われるので、一括処理したときに図と成果物の対応が追えます。関連する図を1ファイルにまとめるか、図ごとにファイルを分けるかは、レビュー単位に合わせて決めてください。

要素の定義と関係線の書き方・矢印の向きと長さが持つ意味の違い

要素は種類を表すキーワードで宣言する形です。class User でクラス、actor User でアクター、participant Server でシーケンス図の参加者になります。宣言を省いて関係線の中に名前を書いても、PlantUMLが要素を自動で作ります。

関係は線と矢印で書きます。Alice -> Bob : Hello はAliceからBobへのメッセージ、--> は破線の矢印です。線を伸ばすと配置に影響します。-> と --> と ---> ではノード間の距離が変わるため、図が詰まって読みにくいときは線の長さを1段伸ばすだけで直ることがあります。

ノートやグループ化で図の読み手に前提と文脈を渡す書き方の基本

図だけでは伝わらない前提は、ノートで補います。note right of Bob のように対象と位置を指定して書くと、該当要素の脇に注記が付きます。図の中に理由を残せるのは、テキストで管理する図の利点の1つです。

要素が増えてきたらグループ化します。package や rectangle で囲めば、サブシステムの境界が図の上で見えるようになります。シーケンス図なら group、条件分岐は alt と else、繰り返しは loop です。囲みを使わずに20要素を並べた図は、ほぼ確実に読まれません。

コメントと別名指定など図の可読性を上げる記述の工夫と使い分け

行頭に半角のアポストロフィを置くと、その行はコメントとして扱われます。スラッシュとアポストロフィを組み合わせた記号で囲めば複数行コメントです。図に出したくない検討メモを、テキストの中に残せます。

要素名が長い場合は as で別名を付けるのが基本です。participant "注文管理サービス" as Order と宣言しておけば、以降の関係線は Order だけで書けます。表示名に日本語を使いつつ記述側を短く保てるので、行数の多いシーケンス図ほど効果的です。表示ラベルの途中で改行したいときは、バックスラッシュとnを組み合わせた記号を挟みます。

シーケンス図・クラス図・ユースケース図の記述例と実務での勘所

ここからは図種別ごとの書き方に入る段階です。設計の現場で使用頻度が高い3種類を中心に、記述例と注意点を並べます。図そのものの読み方や書き分けの理論は各図の解説記事に譲り、この章ではPlantUMLでの表現方法に絞ります。

シーケンス図の記述例と非同期メッセージや分岐・繰り返しの表現

シーケンス図は、オブジェクト間のやり取りを時系列で並べる図です。PlantUMLでは participant で登場人物を宣言し、-> でメッセージを引きます。応答は --> の破線で書き分けるのが慣例です。非同期メッセージには ->> を使い、処理の実行区間を示したいときは activate と deactivate で挟みます。

分岐と繰り返しは複合フラグメントで表します。alt 在庫あり と else 在庫なし、loop 3回、並行処理なら par です。ライフラインやメッセージ、複合フラグメントの意味づけについては、シーケンス図の書き方を解説した記事で図の読み方から整理しています。REST APIのリクエストとレスポンスを1本ずつ並べるだけでも、実装前の認識ずれはかなり減ります。

クラス図の記述例と継承・集約・コンポジション・多重度の書き分け

クラス図は class User の形で宣言し、波括弧の中に属性とメソッドを書きます。可視性は属性名の前に記号を置いて表し、マイナス記号がprivate、プラス記号がpublic、シャープ記号がprotectedに対応します。

関係線の記号が読めれば、クラス図の8割は書けます。継承は <|--、実現は <|..、集約は o--、コンポジションは *-- です。多重度は線の両端に引用符付きで書き添えます。集約とコンポジションの使い分けやライフサイクルの考え方は、クラス図の関連と多重度を扱った記事が詳しいので、記法だけ覚えて意味を取り違えないようにしてください。

ユースケース図の記述例とアクター・システム境界の描き方と粒度

ユースケース図は actor 利用者 でアクターを、丸括弧で囲んだ名前でユースケースを宣言する形式です。両者を --> で結べば関連線になります。システムの境界は rectangle で囲んで表現し、どこまでが開発対象かを図の上で示します。

拡張と包含は関係線にステレオタイプを添えて書きます。二重の山括弧で include や extend を囲む形です。要件定義の場でユースケース図を使うなら、アクターの粒度を先に揃えてください。「利用者」と「管理者」と「経理担当」が同じ図に並ぶと、権限設計の議論が図の外で発散します。アクターと関係の整理手順はユースケース図の書き方の記事にまとめています。

アクティビティ図とコンポーネント図の記述例と使いどころの整理

アクティビティ図は業務フローや処理の流れを書く図で、現在の記法では start と stop の間に処理名をコロンとセミコロンで挟んで並べます。条件分岐は if と then と else、並行処理は fork です。旧記法もまだ動きますが、Graphvizの要否が変わるため新しい記法で書き始めるほうが後の環境依存が減ります。

コンポーネント図は component と interface でシステムの構成要素と接続点を並べる形式です。マイクロサービス構成の全体像や、外部連携の依存関係を1枚で示す用途に向きます。データ構造の側を表したい場合はER図が該当し、こちらはER図の書き方を扱った記事で実装目線の整理をしています。

テーマと標準ライブラリ・レイアウト制御による図の表現の作り込み

PlantUMLは既定の見た目のままでも図として成立しますが、社内標準に合わせたり、崩れたレイアウトを直したりする手段が用意されています。ここでは見た目の統一、部品の再利用、配置の制御を順に扱います。

テーマ指定とスタイル定義で図の見た目を社内標準に統一する手順

組み込みテーマは !theme の1行で切り替わる仕様です。公式サイトのThemeページに一覧があり、配色と枠線がまとめて変わります。コマンドラインからは --theme オプションで外から指定できるので、同じソースを社内向けと社外向けで色だけ変えて出力する運用が組めます。

細かく決めたい場合は skinparam でスタイルを個別に指定します。フォント、背景色、枠線の太さ、影の有無などが対象です。指定はファイル内に直接書くほか、-S オプションでコマンドラインから渡せます。プロジェクト共通の見た目は1つのファイルに集約し、各図はそれを読み込むだけにしておくと、後からの一括変更が1ファイルの編集で済みます。

標準ライブラリのアイコン集とC4モデル記法の取り込み方と注意

PlantUMLには標準ライブラリ（PlantUML Standard Library）が同梱されています。!include に山括弧で囲んだライブラリ名を渡すと、同梱ライブラリからの読み込みが可能です。AWSやAzureのアイコン集、Font Awesomeのアイコン、Kubernetes向けのアイコン集などが含まれており、構成図の見栄えが素の四角形から一段変わります。

アーキテクチャをC4モデルで書くなら、C4-PlantUMLの定義を読み込んで Person や System といったマクロを使います。標準ライブラリ経由で参照できるため、外部ファイルを手元に置く必要はありません。ただし読み込むライブラリが増えるほど描画は遅くなるので、CIで大量に生成する構成では読み込み対象を絞ってください。

レイアウト崩れを直す方向指定と要素の並び替え・エンジンの切替

自動配置は便利な反面、意図と違う並びになることがあります。直す手段は主に3つです。

left to right direction で全体の流れる向きを縦から横へ変える
関係線の長さを -> から -->、---> へ伸ばして距離を稼ぐ
together で並べたい要素を明示的にまとめる

それでも収まらない場合はレイアウトエンジンを替えます。!pragma layout smetana はGraphvizのJava移植版を使う指定で、外部プロセスを起動しません。コマンドラインからは -Playout=smetana と書きます。ELKやvizjsも代替エンジンとして用意されており、大きなクラス図で線が交差しすぎるときは切り替える価値があります。

プリプロセッサで共通定義を切り出す方法と変数・マクロの外部指定

PlantUMLにはプリプロセッサがあり、!include で外部ファイルを読み込めます。共通のスタイル、よく使う要素の定義、社内の記述ルールを別ファイルへ切り出し、各図の先頭で読み込む構成にします。

変数とマクロも使えます。!define で定数を、!procedure で繰り返し使う記述のまとまりを定義でき、コマンドラインからは -D オプションで外から値を差し込める仕様です。環境名だけを変えて開発用と本番用の構成図を出し分ける、といった処理がこれで書けます。共通定義ファイルには .iuml を当てておくと、図の本体と部品がファイル一覧で見分けられます。

CLIとサーバ描画・CIへ組み込むドキュメント運用の設計と手順

PlantUMLの効き目が最も出るのは、図の生成を人の手から外したときです。コマンドラインで一括生成し、CIで再生成し、Gitで差分をレビューする。この3つを組めば、設計書が古びる速度が目に見えて落ちます。

コマンドラインの基本形と出力形式・ディレクトリ一括処理の指定

基本形は java -jar plantuml.jar file1 file2 です。各ファイルから @startXYZ のブロックを探し、図ごとにPNGを出力します。ディレクトリを引数に渡せば配下をまとめて処理でき、対象になる拡張子は前述の一覧のとおりです。

出力形式は指定可能です。SVGで出せば拡大しても線が荒れず、文字列の検索も効くため、Webで公開する設計書に向きます。出力先ディレクトリを分けたい、標準入出力で受け渡したいといった要求にもオプションが用意されており、パイプ処理は -p で行います。

GNU準拠の新しいコマンドライン体系とベータ段階での扱い方の判断

公式のコマンドラインページには、GNUの慣習に沿ってオプション体系を作り直している旨が記載されています。--help、--version、--gui、--verbose のような長い形式が並び、--dark-mode でのダークモード出力や、--http-server による内蔵HTTPサーバの起動（既定ポート4242）も一覧に入っています。

ただしこれはベータ段階の案内です。従来のオプションは移行期間中も動くが今後は文書化されない、と明記されています。手元の作業で新しい書き方を試すのは構いませんが、CIのジョブ定義に組み込むのは正式版が出てからにしてください。ビルドが静かに壊れる形で跳ね返ってくると、原因の特定に時間を取られます。

PlantUML ServerとKrokiを描画基盤に据える構成

チームで使うなら、描画をサーバに寄せる構成が扱いやすくなります。PlantUML ServerのDockerイメージを社内で立ち上げれば、各自の端末にJavaもGraphvizも要りません。Krokiのように複数の作図ツールをまとめて受け付けるサーバを置く手もあり、PlantUMLとMermaidを併用する現場ではこちらが収まります。

サーバ構成にする場合、図のテキストがネットワークを流れる点は設計に織り込んでください。既定の公開サーバをそのまま使うと、社外に設計情報を送ることになります。自社内にコンテナを1つ置くだけで避けられる話なので、導入初日に決めておく事項です。

CIで図を再生成し画像の差分を検知する運用の組み立て方と順序

CIに組み込む形はいくつかありますが、実装が軽いのは次の順序です。

.puml ファイルをリポジトリの決まった場所に置く
プルリクエスト時にCIでPlantUMLを走らせ、画像を生成する
生成物をコミット済みの画像と比較し、差があれば失敗させる
開発者は図を更新して画像を再生成し、両方を同じコミットに含める

画像をリポジトリに含めるかどうかは運用方針によって分かれる部分です。含めればGitHub上でそのまま図を確認できる一方、バイナリ差分は積み上がる。含めないなら、ドキュメント生成のたびにサーバ描画で解決する構成にします。設計書とコードの整合性を機械的に保つ考え方は整合性駆動開発の解説記事で扱っており、PlantUMLはその実装手段の1つに位置づけられます。

Gitで図をレビュー対象に載せる差分管理の進め方と定着のルール

図がテキストなら、プルリクエストのレビューで「この矢印が増えた」「この関係が消えた」が行単位で読めます。画像ファイルだけを差し替える運用では、変更点を目視で探すことになり、レビューは形骸化します。

運用を根づかせるには、図の更新をコードの変更と同じコミットに含めるルールを先に決めることです。設計書を別リポジトリや共有フォルダに置いたままだと、更新は後回しになりがちです。ドキュメントが書かれない理由と、書き続ける仕組みの作り方はドキュメント化を扱った記事で整理しています。既存システムの設計書が現状と乖離していて手を付けられない場合は、保守運用・内製化支援で現行仕様の可視化から運用ルールの定着までを引き受けています。

MermaidやGUI作図ツールとの比較で決める採用条件と限界

テキストで図を書くツールはPlantUMLだけではありません。どれを選ぶかは、図の種類と、図を置く場所と、チームの人数で決まります。ここでは比較の軸を示したうえで、採用する条件と見送る条件を切り分けます。

MermaidとPlantUMLの守備範囲と描画環境の具体的な違い

両者はどちらもテキストから図を出しますが、得意分野が分かれます。PlantUMLはUML図の網羅性が高く、シーケンス図・クラス図・ユースケース図・ステート図・配置図まで1つの記法で書けます。Mermaidはフローチャートやガントチャート、ER図に強く、GitHubのMarkdownやNotionなどがそのままレンダリングする点で手軽です。

観点	PlantUML	Mermaid
UML図の網羅性	広い	限定的
実行環境	Javaまたはサーバ	ブラウザで完結
GitHub表示	拡張か画像が必要	そのまま描画
外部依存	Graphvizが要る図あり	追加依存なし
見た目の調整	細かく指定できる	指定できる範囲が狭い

結論を先に言えば、READMEや課題票に図を1枚添えたいだけならMermaidで足ります。Mermaid記法の使い方をまとめた記事に基本形があるので、そちらで済む案件かを先に判定してください。設計書としてクラス図やステート図まで揃える必要が出た時点で、PlantUMLへ寄せる価値が生まれます。

GUI作図ツールと比べた場合の編集コスト・学習コストの実際の差

GUI作図ツールは、最初の1枚を作る速度でテキスト作図に勝ちます。図形を置いて線でつなぐ操作は説明が不要で、非エンジニアも同じ土俵に立てます。ここを否定しても現場は動きません。

差が出るのは2枚目以降と、修正のときです。要素を1つ挟み込むためにGUIで全体を並べ直す作業が、テキストなら1行の挿入で済みます。学習コストは記法の暗記ではなく、レイアウト制御の癖を掴むまでの時間だと考えてください。矢印の長さや left to right direction で配置が変わる感覚が身につくまで、おおむね数枚ぶんの試行が要ります。

PlantUMLを導入して効果が出る条件と見送るべき場面の線引き

採用して効果が出るのは、次の条件が重なる場合です。図の更新が月に何度も発生し、図とコードを同じリポジトリで管理でき、レビュー文化がすでにある。この3つが揃っているなら、導入初月から差分レビューの効果が出ます。

逆に、見送るべき場面もはっきりしています。図を1枚だけ作って提案書に貼り、以後更新しないなら、テキスト作図の利点は回収できません。図の配置やフォントを細かく作り込んだ営業資料も同様で、自動配置と戦う時間のほうが長くなります。UMLを読める人がチームに1人もいない場合も、まずMermaidのフローチャートから始めるほうが定着します。ここは「状況次第」で濁さず、投資対効果が出ない構成では入れない判断をしてください。

テキスト作図の導入でつまずく進め方と回避のための具体策と順序

失敗の型はおおむね決まっています。最も多いのは、既存の設計書をすべてPlantUMLへ書き直そうとして途中で止まるパターンです。数百枚の図を一括で移す計画は、ほぼ完走しません。

回避策は移行範囲を絞ることです。今後3か月で確実に変更が入る機能に限って図を起こし、変更のたびに更新する運用を1周させます。1周回れば、更新されない図の存在自体が問題として見えてきます。もう1つの失敗は、描画環境を各自任せにして「自分の環境では出る」が乱発する状態です。サーバ描画かDockerで環境を1つに揃えれば、この種の問い合わせはほぼ消えます。

症状別の切り分け手順とエラーメッセージから復旧するまでの流れ

PlantUMLの不具合は、Java・Graphviz・記法・出力先・エディタ拡張のどこかに収まる構造です。原因の層を先に特定すれば、対処は短く済みます。ここでは症状ごとの切り分けを順に並べます。

Javaが見つからない場合と版が古い場合の確認手順と対処の順序

起動時点で落ちるなら、Java側を疑います。java -version を実行し、バージョンが表示されるかを確認してください。表示されない場合はJavaが入っていないか、パスが通っていません。表示されても8系だった場合は、Java 11以降へ更新するか、Java 8向けの別ビルドへ切り替えます。

環境変数 JAVA_HOME が古いJDKを指したまま残っているケースもよくあります。複数のJDKを入れている端末では、コマンドで見えているJavaとツールが参照するJavaが食い違います。CIで動かない場合は、ランナーのイメージに含まれるJavaの版をログに出して確かめるのが確実です。

Graphvizのエラーとレイアウトエンジン切り替えでの回避

シーケンス図は出るのにクラス図だけ失敗する。この症状はGraphviz側の問題とみて構いません。dotが入っていないか、実行ファイルの場所をPlantUMLが見つけられていない状態です。

確認には --check-graphviz を使うのが基本です。導入し直すのが正攻法ですが、端末に管理者権限がない、CIイメージにdotを足せないといった事情があるなら、!pragma layout smetana で同梱のJava移植版に切り替える回避策があります。外部プロセスを起動しないぶん、コンテナ内での実行も安定します。ただしレイアウト結果はdotと完全に同じにはならないため、既存の図を切り替える際は見た目の変化を確認してください。

記法ミスで図が出ない場合のエラー表示の読み方と原因の絞り込み

記法に誤りがあると、PlantUMLは画像の中にエラー内容を描いて返す仕様です。何行目の何が解釈できなかったかが図として出るので、まずその行を見ます。囲みの閉じ忘れ、全角スペースの混入、要素名に使えない記号、この3つで大半が説明できます。

日本語を含む図では文字コードも疑ってください。ファイルをUTF-8で保存していないと、ラベルが化けたり解釈に失敗したりします。原因の切り分けには、問題の図を半分に削って通るかどうかを見る方法が早道です。通れば削った側に原因があり、通らなければ残した側にあります。

画像が出力されない場合の出力先の確認とサイズ上限の引き上げ方

コマンドは正常終了するのに画像が見つからない場合、出力先を取り違えている可能性があります。既定では入力ファイルと同じディレクトリに書き出されるため、別の場所を探していないか確認してください。書き込み権限がないディレクトリを指定していると、無言で失敗することもあります。

図が大きすぎて途中で切れる症状も既知の事象です。PlantUMLには描画サイズの上限が設けられており、大きなクラス図では上限に当たります。図を分割するのが本筋ですが、どうしても1枚に収めたい場合は上限値を引き上げる設定を使います。詳細なログが要るときは -v で処理内容を出力させてください。

エディタ拡張でプレビューが表示されない場合に確認する設定と手順

VS Codeで拡張を入れたのにプレビューが出ない場合、確認する箇所は2つです。1つは描画方式の設定で、ローカル描画ならJavaのパス、サーバ描画ならサーバのURLが正しいかを見ます。もう1つはファイルの拡張子で、拡張が認識する5種類のいずれかになっているかを確かめます。

拡張を入れ直しても直らない場合は、拡張のログを開いて実際に呼ばれているコマンドを確認します。Mermaidの拡張と併用していて表示が競合するケースもあるため、VS CodeでMermaidを使う手順の記事と読み比べて、どちらの拡張が該当ファイルを処理しているかを切り分けてください。IntelliJ IDEAでは公式のPlantUML統合プラグインを入れると、記述と同時にプレビューが更新されます。

ライセンスの選び分けと商用利用・自社製品への組み込みの判断基準

PlantUMLのライセンスは1本ではありません。同じ機能に見えて、選んだライセンスによって同梱される機能が変わります。社内利用なら気にせず済みますが、製品へ組み込むなら最初に整理しておく領域です。

7種類のライセンスと同梱される機能の違いを示す比較の見取り図

公式のダウンロードページでは、GPLv3・GPLv2・LGPL・ASL（Apache 2.0）・BSD・EPL 2.0・MITの7つが並び、それぞれにコンパイル済みjarとソースコードが用意されています。機能の差は公式サイトの表で確認できます。

機能	同梱されるライセンス版
ditaa連携	GPLv3・GPLv2・LGPL
Jcckit	GPLv3・GPLv2
Sudoku	GPLv3・GPLv2
ELKレイアウト	EPL版のみ
Graphviz非同梱	LGPL版

公式サイトはGPL版を「機能が最も揃った版」として推奨しています。一方で、他の版もUML図の生成そのものはすべてできる、と明記されています。ditaaやSudokuを使わないなら、機能面での不足はまず起きません。

商用利用と生成した図の権利関係で事前に確認すべき条項の範囲と根拠

商用利用は可能です。ツールを社内の開発業務で使い、生成した図を納品物の設計書に載せることに制限はありません。生成された図そのものは、記述したテキストの作成者の成果物として扱われます。

注意が要るのは、ツール本体を再配布する場合です。GPL版のjarを自社製品に同梱すれば、GPLの条件が製品側にかかります。この一点だけは法務と確認してください。条項の解釈が要る場面では、公式FAQの記載を根拠として提示できるようにしておくと話が早く進みます。

自社製品やSaaSへ組み込む場合の配布形態ごとの判断基準の整理

判断は配布形態で分かれます。社内利用や受託開発の成果物に図を含めるだけなら、どのライセンスでも支障ありません。自社パッケージにjarを同梱して顧客へ渡すなら、Apache 2.0・MIT・BSDのいずれかを選ぶのが素直な選択です。

SaaSとしてサーバ側で描画し、利用者には画像だけを返す構成なら、再配布に当たらないためGPL版でも運用できるという整理が一般的です。ただしこれは案件ごとに結論が変わる領域なので、配布形態を図にしたうえで法務判断を仰いでください。GraphvizのバイナリをバンドルしたくないならLGPL版を選ぶ、という技術要件からの逆算も判断材料になります。

よくある質問

PlantUMLの導入前後によく挙がる質問を、公式ドキュメントの記載（2026年8月時点）に沿って回答します。

PlantUMLの読み方は何ですか？

「プラントユーエムエル」と読みます。ファイルの拡張子や省略表記として使われるpumlは「ピーユーエムエル」と読まれることもあります。名前の由来は、UMLの図を植物のように自然に生やすというイメージで、日本語のドキュメントでもカタカナ表記より英字表記のほうが通りが良い場面が多いはずです。社内資料で読み方を統一しておくと、口頭のやり取りで齟齬が出ません。

PlantUMLのファイルの拡張子は何ですか？

標準の拡張子は .puml です。VS Code拡張のpackage.jsonでは、.wsd・.pu・.puml・.plantuml・.iuml の5つがPlantUMLの言語として登録されています。コマンドラインでディレクトリを一括処理する場合はさらに広く、.txt や .md、.java などのファイル内に書かれた @startXYZ ブロックも探索対象です。1ファイルに複数の図を書いた場合は、囲みのブロック単位で個別の画像として出力されます。

PlantUMLはJavaなしで使えますか？

本体のplantuml.jarはJavaランタイム上で動くため、ローカル描画にはJavaが必要です。公式のクイックスタートは最低推奨をJava 11としています。ただしJavaを入れずに使う経路も複数あり、公式のPlantUML Server、Dockerイメージ、VS Code拡張の描画先をサーバに切り替える設定、Krokiのような描画サービスを使えば、端末にJavaを入れずに図を生成できます。機密を含む図では、公開サーバではなく自社内に立てたサーバを使ってください。

PlantUMLは商用利用できますか？

商用利用はできます。GPLv3・GPLv2・LGPL・Apache 2.0・BSD・EPL 2.0・MITの中から、条件に合うライセンスを選んで入手する形です。生成した図は記述者の成果物という扱いです。注意が要るのはツール本体を自社製品へ同梱して再配布する場合で、選んだライセンスの条件が製品側にかかります。同梱機能にも差があり、ditaa連携はGPL系とLGPL、ELKレイアウトはEPL版にだけ含まれます。

PlantUMLとMermaidはどう違いますか？

どちらもテキストで図を書きますが、守備範囲と実行環境が異なります。PlantUMLはUML図の網羅性が高く、クラス図やステート図まで1つの記法で書ける一方、ローカル描画にはJavaが、図によってはGraphvizが要ります。Mermaidはフローチャートやガントチャートに強く、GitHubのMarkdown上でそのまま描画される手軽さが持ち味です。設計書としてUML図を揃えるならPlantUML、READMEに1枚添えるならMermaid、という切り分けが実務的です。