PlantUMLとは？使い方・記法・インストールと.puml拡張子【v1.2026.9】

PlantUML（プラントユーエムエル）は、テキストで書いた数行の記述からUML図を生成するオープンソースのツールです。@startuml と @enduml の間にメッセージのやり取りを書けばシーケンス図を、クラスの宣言や関係を書けばクラス図を、PNGやSVGで出力できます。この記事では、2026年10月17日公開の v1.2026.9 を手元で動かして確かめた内容をもとに、記法の書き方と描画結果、インストール、.puml拡張子、Graphvizの要否、CLIとCIでの使い方、Mermaidとの選び分けまでを順に説明します。

まとめ：PlantUMLの要点（v1.2026.9時点）

• テキストからUML図を生成するOSS。2009年4月22日に初公開され、作者はArnaud Roques氏。最新版は v1.2026.9（2026年10月17日）
• 拡張子は .puml が標準。VS Code拡張は .wsd・.pu・.puml・.plantuml・.iuml の5つを認識する
• ローカルで動かすにはJavaが必要。公式の最低推奨はJava 11で、Java 8向けの別ビルドもある
• 1.2026.6の検証では、Graphviz未導入のMacで既定設定のクラス図を描くと「Cannot find Graphviz」のエラー画像が出た。1.2026.7からは同梱のSmetanaへ自動で切り替わり、クラス図なども描画される
• CIでは --check-syntax を使う。構文エラーがあると終了コード200で止まる
• GitHubのMarkdownが図として表示するのはMermaidで、PlantUMLは表示しない。図をGitHub上で見せたいならMermaid、UMLの種類と細かい表現が要るならPlantUML
• 商用利用は可能。GPLv3・GPLv2・LGPL・Apache 2.0・BSD・EPL 2.0・MITの各版から選んで入手する

PlantUMLの仕組みと対応する図の種類

テキストから図を生成する仕組みとモデリングツールとの違い

PlantUMLは、記述を解析して図の要素と関係を組み立て、配置を計算して画像を書き出すジェネレータです。図の実体がテキストなので、Gitの差分で「どの矢印が増えたか」を読めます。プルリクエストで設計変更をレビューできるのは、この性質があるからです。

公式のFAQは、相互継承のような矛盾した図も描けてしまうことを理由に、PlantUMLを「モデリングツールというより作図ツール」と位置づけています。モデルの整合性検証やコード生成まで任せたいなら、Enterprise Architectのようなモデリングツールの領分です。PlantUMLが向いているのは、設計の意図を短時間で図にし、ソースコードと同じリポジトリで版管理する使い方です。

PlantUMLで描ける図の種類

公式サイトのメニューに並ぶ図は次のとおりです。UMLの図のどれを実務で書くべきかはUMLの14種類の図と実務で使う4種類で整理しています。

.puml拡張子とファイルの分け方

エディタとCLIが認識する拡張子

標準の拡張子は .puml です。VS Code拡張「PlantUML」（jebbs.plantuml）のMarketplaceページには、対応する拡張子として .wsd・.pu・.puml・.plantuml・.iuml の5つが書かれています。.pu と .puml は中身の書式が同じで、違うのはエディタが言語を判定するときの名前だけです。チーム内では1つに揃え、迷ったら .puml にしてください。

コマンドラインでディレクトリを指定した場合は、公式のコマンドライン解説によると .txt・.tex・.java・.htm・.html・.c・.h・.cpp・.apt・.pu・.puml・.hpp・.hh・.md の各ファイルから @startXYZ〜@endXYZ のブロックが探されます。Javaのソースコメントや Markdown に図を埋め込んだまま画像にできるのは、この仕様のためです。

共通定義を.iumlに切り出す!include

フォントや配色、システム名のように複数の図で使い回す設定は、別ファイルに分けて !include で読み込みます。部品側を .iuml、図の本体を .puml にしておくと、ファイル一覧で両者を見分けられます。

' inc/common.iuml（共通定義）
skinparam shadowing false
!$SYSTEM = "受注システム"

' order.puml（図の本体）
@startuml
!include inc/common.iuml
title $SYSTEM のシーケンス
利用者 -> $SYSTEM : 注文
@enduml

!$SYSTEM はプリプロセッサの変数で、図の中の $SYSTEM が「受注システム」に置き換わって描画されます。行頭の ' はコメントです。1つのファイルに @startuml login と @startuml logout のように名前を付けたブロックを複数書くと、login.png と logout.png が別々に出力されます。

PlantUMLのインストール手順：Java・plantuml.jar・VS Code

Javaの動作確認とplantuml.jarによる初回描画

PlantUMLはインストーラを持たず、plantuml.jar を1つ置けば動きます。手順はWindows・macOS・Linuxで共通です。

1. java -version でJavaが入っているか確かめる。公式のクイックスタートは最低推奨をJava 11とし、移行できない環境向けにJava 8対応の別ビルド（plantuml-java8-1.2026.9.jar）を用意している
2. GitHubのリリース一覧から plantuml-1.2026.9.jar を取得する
3. 次の hello.puml を作り、java -jar plantuml-1.2026.9.jar hello.puml を実行する。同じフォルダに hello.png ができれば完了

@startuml
Alice -> Bob : こんにちは
Bob --> Alice : 了解
@enduml

手元の環境（Temurin 25）では、java -jar plantuml-1.2026.9.jar --version が「PlantUML version 1.2026.9」とJavaの版、画像サイズの上限（PLANTUML_LIMIT_SIZE: 4096）を表示しました。上限を超える大きな図が途中で切れるときは、環境変数 PLANTUML_LIMIT_SIZE を引き上げます。

VS Code拡張によるプレビューと画像出力

日々の作図はVS Code拡張「PlantUML」（jebbs.plantuml、公式リポジトリの最新は2.18.1）で行うのが手早い方法です。.puml を開いて Alt+D を押すと「Preview Current Diagram」のプレビューが開きます。画像にするときはコマンドパレットの「Export Current Diagram」を使い、既定では out フォルダに書き出されます。本記事と同じ版で描画するには、設定の plantuml.jar に取得した plantuml-1.2026.9.jar の絶対パスを指定してください。未指定の場合は拡張に同梱されたjarが使われます。

描画の方式は設定 plantuml.render で選び、値は Local（手元のJavaで描画）と PlantUMLServer（サーバーに描画させる）の2つです。PlantUMLServer にする場合は plantuml.server に描画サーバーのURLを入れます。

Javaを入れずに使う方法：サーバー・Docker・ネイティブ版

端末にJavaを入れられないときの選択肢は3つあります。

• PlantUML Server：公式のplantuml-serverのREADMEにある docker run -d -p 8080:8080 plantuml/plantuml-server:jetty で社内に描画サーバーを立て、VS Code拡張の描画先に指定する。Docker Hubのタグは2026年10月18日時点で v1.2026.8 が最新
• ネイティブ版：v1.2026.9 のリリースには native-plantuml の Windows（amd64）・Linux（amd64／arm64）・macOS（arm64）向けZIPが含まれる。公式のBUILDING.mdは、plantuml.jar と同じコードを GraalVM でネイティブバイナリにした、画面を持たないCLIと説明している
• ブラウザ版：同じくリリースに含まれる js-plantuml は、TeaVMでJavaScriptに変換した版で、サーバー無しにブラウザ内で描画する

Intel Macのように、ネイティブ版の配布が無いプラットフォームもあります。その場合はサーバーかJavaを選びます。

Graphvizの要否と1.2026.7からのSmetana自動切り替え

ここは古い解説記事と現在の挙動が最も食い違う点です。公式のGraphviz解説は、ユースケース図・クラス図・オブジェクト図・コンポーネント図・配置図・ステート図・旧記法のアクティビティ図の7種類が配置計算にGraphvizを使い、それ以外（シーケンス図など）は使わないと説明しています。Windows向けには 1.2020.21 以降、最小構成の dot.exe が plantuml.jar に同梱されています。同梱しない版が要るときはLGPL版を選びます。

Graphvizを入れていないMacで、同じクラス図を2つの版で描画して比べました。

差が出た理由はソースコードにあります。2026年7月16日のコミット「fall back to Smetana when Graphviz/dot is unavailable」で、dot が見つからないときは同梱のJava移植版レイアウトエンジン「Smetana」を使う分岐が入りました。v1.2026.9 の CucaDiagram.java には this.isUseSmetana() || this.dotIsAvailable() == false の条件が残っています。この変更を含む最初の正式版は、2026年8月25日公開の v1.2026.7 です。

注意点が2つあります。1つは表示の古さで、1.2026.9 でも --version は「Dot executable does not exist」「only sequence diagrams will be generated」と表示しますが、実際にはクラス図も描画されます。もう1つは 1.2026.6 以前の終了コードで、エラー画像を書き出しても0を返すため、CIの成否だけを見ていると壊れた画像がそのままドキュメントに載ります。古い版を使い続けるCIでは、Graphvizを入れるか、図の先頭に !pragma layout smetana を書いてください。この指定は 1.2021.5 から使えます。

Graphvizを入れる理由が残るのは、図の配置を既存の出力と揃えたいチームです。公式はSmetanaを今も「実験的」と書いているので、配置がdotと完全に一致する保証はありません。社内で配る画像の見た目を固定したいなら、Graphvizの版を揃えて入れ、--check-graphviz で認識されているか確かめます。

PlantUMLの記法：シーケンス図・クラス図・アクティビティ図・ユースケース図の例

どの図も、@startuml〜@enduml の間に「要素の宣言」と「関係の線」を1行ずつ書く点は同じです。以下のコードはすべて v1.2026.9 で描画を確かめ、画像は掲載コードをそのまま出力したものです。

シーケンス図：分岐と処理中の帯

@startuml
actor 利用者 as U
participant "Webアプリ" as W
database "DB" as D
U -> W : ログイン(ID, パスワード)
activate W
W -> D : ユーザー照会
D --> W : ユーザー情報
alt 認証成功
  W --> U : トップページ
else 認証失敗
  W --> U : エラーメッセージ
end
deactivate W
@enduml

-> は実線（呼び出し）、--> は点線（応答）です。alt／else／end で条件分岐の枠を作り、繰り返しは loop、並行処理は par で同じように囲みます。activate と deactivate の間には、処理中を示す縦長の帯が出ます。ライフラインや複合フラグメントの意味はシーケンス図の書き方とライフライン・複合フラグメントで解説しています。

クラス図：継承・集約・コンポジションと多重度

@startuml
class 注文 {
  - 注文ID : String
  - 注文日 : Date
  + 合計金額() : int
}
class 注文明細 {
  - 数量 : int
}
class 商品
class 会員
abstract class 支払い
class クレジット支払い
会員 "1" -- "0..*" 注文
注文 *-- "1..*" 注文明細
注文明細 --> 商品
支払い <|-- クレジット支払い
注文 o-- 支払い
@enduml

線の記号で関係を描き分けます。<|-- が継承、*-- がコンポジション（全体と生死を共にする部品）、o-- が集約、--> が向きのある関連です。"1" -- "0..*" のように線の両端へ文字列を置くと多重度になります。- は private、+ は public の可視性です。集約とコンポジションの使い分けはクラス図の書き方と集約・コンポジションの違いにまとめています。

アクティビティ図：条件分岐と並行処理

@startuml
start
:注文を受け付ける;
if (在庫あり?) then (はい)
  :出荷を手配する;
else (いいえ)
  :入荷待ちを通知する;
endif
fork
  :請求書を送る;
fork again
  :ポイントを付与する;
end fork
stop
@enduml

処理は : で始めて ; で閉じます。この新しい記法はGraphvizを使わずに描かれるので、Graphvizの要否を気にせず書けます。fork〜end fork の間が並行して進む処理です。

ユースケース図：アクターとシステム境界

@startuml
left to right direction
actor 会員
actor 管理者
rectangle ECサイト {
  usecase "商品を検索する" as UC1
  usecase "注文する" as UC2
  usecase "決済する" as UC3
  usecase "在庫を登録する" as UC4
}
会員 --> UC1
会員 --> UC2
UC2 ..> UC3 : <<include>>
管理者 --> UC4
@enduml

rectangle の枠がシステム境界になり、left to right direction でアクターを左、ユースケースを右に並べます。..> と <<include>> を組み合わせると包含関係です。ユースケースの粒度の決め方はユースケース図の書き方と要件定義での使い方を参照してください。

PlantUMLでDFD（データフロー図）を描く方法

公式サイトの図の一覧にDFDは載っていません。用意されている図形を見立てて描きます。外部実体を rectangle、プロセスを usecase（楕円）、データストアを database にし、矢印のラベルにデータの名前を書きます。

@startuml
left to right direction
skinparam rectangleBorderThickness 2
rectangle "顧客" as C
usecase "1.0\n注文受付" as P1
usecase "2.0\n在庫引当" as P2
database "D1 注文" as D1
database "D2 在庫" as D2
C --> P1 : 注文情報
P1 --> D1 : 注文データ
P1 --> P2 : 引当依頼
D2 --> P2 : 在庫数
P2 --> C : 納期回答
@enduml

プロセス番号（1.0、2.0）をラベルの1行目に入れておくと、下位のDFDへ分解したときに番号で対応を追えます。usecase と rectangle を使う図はGraphvizで配置されるため、1.2026.6 以前ではGraphvizか !pragma layout smetana が必要です。DFDとシステム関連図の粒度の違いはデータ連携図の書き方｜システム関連図とDFDの粒度で扱っています。

コマンドラインによる一括出力とCIでの構文チェック

GNU形式の新しいオプションと旧オプションの対応

公式のコマンドライン解説は、GNUの規約に沿った新しいオプション体系を「beta」として公開しています。旧オプションは移行期間中は使えますが、今後は解説されません。v1.2026.9 の --help は新形式だけを表示し、旧形式の -tsvg を渡してもSVGが出力されました。ソースの CliFlag.java では、旧オプションに非推奨（DEPRECATED）の印が付いています。

終了コードと出力先指定（output-dir）の相対パスの挙動

v1.2026.9 で実際に返った終了コードは、--help の記載と一致しました。

存在しないパスを直接指定すると50でしたが、存在しないフォルダにワイルドカードを付けて指定する（"nothing/*.puml"）と、IllegalArgumentException の例外で終了コード1が返りました。CIでは0以外をすべて失敗として扱うのが安全です。

出力先の指定にも癖があります。--output-dir out のように相対パスを渡すと、out は実行した場所ではなく各.pumlと同じフォルダの下に作られました（docs/a/out/、docs/a/b/out/）。1か所に集めたいときは --output-dir "$PWD/out" のように絶対パスを渡します。この場合はサブフォルダの構造が平らになるため、別々のフォルダに同じ名前の.pumlがあると画像が上書きされます。

GitHub Actionsによるプルリクエスト時の構文チェック

図の壊れたままのマージを防ぐには、プルリクエストで --check-syntax を走らせます。画像を生成しないので描画より軽く、構文エラーがあれば終了コード200でジョブが落ちます。

name: plantuml-check
on: pull_request
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-java@v6
        with:
          distribution: temurin
          java-version: '21'
      - run: curl -sL -o plantuml.jar https://github.com/plantuml/plantuml/releases/download/v1.2026.9/plantuml-1.2026.9.jar
      - run: java -jar plantuml.jar --check-syntax "docs/**/*.puml"

"docs/**/*.puml" の ** はサブフォルダまでたどる指定で、シェルに展開させないよう引用符で囲みます。v1.2026.9 で同じコマンドを実行すると、正しいファイルだけなら0、1つでも構文エラーがあれば200が返りました。jarの版をURLで固定しておくと、版が上がって描画結果が変わったときに差分の原因を追えます。

PlantUMLとMermaidの比較：描画環境と図種による選択基準

テキストで図を書く道具として、最もよく比べられるのがMermaidです（最新版は2026年10月時点で12.2.0）。違いは図の表現力よりも「どこで描画されるか」に出ます。

GitHubの図の作成に関するドキュメントが挙げる構文は mermaid・geoJSON・topoJSON・ASCII STL の4つで、plantuml は入っていません。GitLabはMarkdownのドキュメントでMermaidとPlantUMLの両方を挙げますが、PlantUMLは管理者がPlantUMLサーバーを用意して連携を有効にする必要があります。Mermaidの構文一覧には、タイミング図・配置図・オブジェクト図に当たるページがありません。

選び方ははっきりしています。READMEやIssueの中で図を見せたい、閲覧者の環境に何も入れさせたくないならMermaidです。配置図やタイミング図まで同じ記法で揃えたい、!include で部品を共通化して数十枚の設計図を管理したいならPlantUMLを選びます。両方を併用するチームでは、リポジトリのREADMEはMermaid、設計書フォルダの図はPlantUMLと置き場所で分けると混乱しません。Mermaidの書き方はMermaid記法の使い方とLive Editorで紹介しています。

逆に、PlantUMLを選ばないほうがよい場面もあります。提案資料のように1枚の見た目をピクセル単位で作り込みたい図や、システム構成をクラウドのアイコンで描く図は、GUIの作図ツールのほうが早く仕上がります。構成図の描き方はアーキテクチャ図の書き方とC4モデルを参照してください。要件定義の段階から設計書の作り方を整えたい場合は、弊社の要件定義・RFP作成・PMO支援でもご相談を受けています。

PlantUMLの安全性と商用利用

公開サーバーへの送信とセキュリティプロファイル

安全性で最初に確かめるべきは、図の文字列をどこへ送っているかです。公開のオンラインサーバーやURL形式の画像リンクは、図のテキストをDeflateで圧縮し、Base64に近い独自の変換をかけた文字列としてURLに載せます。暗号化ではないため、URLから元の記述を復元できます（v1.2026.9 には --decode-url オプションもあります）。社外秘の設計を描くなら、手元のjarか社内に立てたPlantUML Serverで描画してください。

もう1つは、図の中から読みに行けるファイルとURLの範囲です。公式のセキュリティ解説によると、環境変数 PLANTUML_SECURITY_PROFILE の既定値は LEGACY で、ローカルファイルとURLへのアクセスを旧版と同じく制限なしで許します。他人が書いた図を描画するサーバーでは、ローカルファイルとURLの読み込みを禁止する SANDBOX か、許可リスト方式の ALLOWLIST に絞ります。公式の plantuml-server は既定で INTERNET（許可リスト以外のローカルファイルは不可、80・443番ポートのURLは可）に設定されています。

ライセンスの選び方と商用利用

PlantUMLは1つのソースから複数のライセンス版を配布しており、商用利用はどの版でも可能です。公式のダウンロードページはGPLv3・GPLv2・LGPL・Apache 2.0（ASL）・BSD・EPL 2.0・MITの7種類を掲げ、v1.2026.9 のGitHubリリースにはこれに加えて mit-light 版と Java 8 版のjarもあります。

社内で図を描くだけなら、標準の plantuml.jar（GPLv3）で問題ありません。自社製品やSaaSにPlantUMLを組み込んで配布する場合は、ソースの開示義務が無いApache 2.0・BSD・MIT版が候補になり、その代わりditaaは使えません。ただし、再配布時には選んだライセンスに従って著作権表示やライセンス文を保持し、Apache 2.0では該当するNOTICEや変更表示の条件も確認してください。ELKレイアウトはELKの解説では1.2024.6以降のplantuml.jarに同梱とされる一方、ダウンロードページの比較表はEPL版だけに印を付けており、記述が揃っていません。ELKを製品で使うなら、選んだ版のjarで !pragma layout elk が動くかを確かめてから決めてください。

よくある質問

PlantUMLの読み方は何ですか？

「プラントユーエムエル」と読みます。UMLはUnified Modeling Languageの略です。

PlantUMLの拡張子は.puと.pumlのどちらですか？

標準は .puml です。.pu も同じ書式で、VS Code拡張とCLIのどちらでも認識されます。チーム内でどちらかに統一してください。

PlantUMLはJavaが必要ですか？

plantuml.jar で描画するならJava 11以上が推奨です。Javaを入れられない場合は、社内のPlantUML Server、v1.2026.9 で配布されているネイティブ版（Windows・Linux・Apple シリコンのmacOS）、ブラウザ版のいずれかを使います。

PlantUMLをWindowsにインストールするには？

Javaを入れたうえで、GitHubのリリースから plantuml-1.2026.9.jar を取得し、java -jar plantuml-1.2026.9.jar 図.puml で実行します。インストーラはありません。Windows向けのjarにはGraphvizのdot.exeが同梱されているため、Graphvizを別に入れなくても描画できます。

PlantUMLは安全ですか？

手元のjarなら描画サーバーへの送信は不要ですが、外部URLを読み込む記述があれば通信は発生します。外部通信を禁止する場合は、セキュリティプロファイルをSANDBOXに設定してください。公開のオンラインサーバーは図の文字列をURLに載せて送るので、社外秘の図には使わないでください。他人の図を描画するサーバーでは PLANTUML_SECURITY_PROFILE を SANDBOX か ALLOWLIST にします。

関連記事

• UMLとは：仕様2.5.1の14種類の図と実務で使う4種類・PlantUMLとMermaidの書き方
• シーケンス図とは？UMLの書き方とライフライン・複合フラグメント・Mermaid実装を解説
• クラス図とは？UMLの書き方・関連や多重度・集約とコンポジションの違いを解説
• Mermaid記法の使い方｜無料のLive Editor（mermaid.live）でフローチャート・シーケンス図を作成
• データ連携図の書き方｜システム関連図とDFDの粒度と記法・Mermaidでの版管理