本記事の構成および論理分析にはAI(人工知能)を使用しています。情報の正確性は、システム管理者(UNIXユーザー)による手動検証済みです。
WordPressのリンク切れ候補をPCから調べる「wordpress-link-checker」を作りました【無料・Python】| UNIX Cafe

WordPressで記事を書き続けていると、以前貼ったリンクが今もちゃんと開けるのか、気になることはありませんか。
自分のサイトでページのURLを変えたり、紹介した外部サイトのページが移動・削除されたりすると、リンクは知らないうちに切れてしまいます。記事が増えるほど、ひとつずつブラウザで開いて確認するのは大変です。
しかも、知りたいのは「どのURLがエラーになったか」だけではありません。「そのリンクを、どの記事の、どこに貼っていたか」まで分かれば、すぐに修正に取りかかれます。
そこで、サイトの公開ページからリンクを集めて検査し、リンクを貼っている記事(このツールでは「掲載元」と呼びます)と検査結果を1つのレポートにまとめる wordpress-link-checker を作りました。GitHubで無料公開しています。
wordpress-link-checkerをGitHubで見る
macOSまたはLinuxの「ターミナル」にコマンドを入力して使うツールです。動かすにはPython 3.11以上が必要ですが、追加でインストールするPythonパッケージはありません。ボタンで操作するような画面(GUI)はありません。
WordPressにプラグインを入れたり、データベースに接続したりする必要もありません。ただし、検査のときは実際にサイトのページやリンク先へアクセスします。サーバーに負担をかけないよう、最初は少ないページ数から試してください。
1. リンク切れの候補と、それを貼っている記事がまとめて分かります
wordpress-link-checkerは、指定したWordPressサイトの公開ページ(誰でも見られる状態のページ)を読み込み、その中にあるリンクを調べます。自分のサイト内へのリンクも、外部サイトへのリンクも対象です。ただし、Amazonの直接リンクや既知の短縮リンクなど、通信前に除外するものもあります。
調べる記事(掲載元ページ)の集め方は、次の3つから選べます。
- サイトマップ(サイト内のページ一覧を書いたファイル)から集める。
- WordPressの公開REST API(WordPressが標準で用意している、記事情報を取り出す仕組み)から集める。
- 調べたいページのURLを自分で指定する。
同じリンクを複数の記事に貼っている場合、1回の実行の中では同じリンク先を何度も検査せず、結果を使い回します。そのうえで、どの記事に何か所貼ってあるかは、記事ごとにきちんと記録します。
「ページが見つからない」ことを示す404や410が返ってきても、すぐにはリンク切れと決めつけません。60秒以上空けてから、もう一度確認します。また、転送(リダイレクト)先で表示できたリンク、ログインが必要だったりアクセスを拒否されたりして確認できなかったリンク、通信そのものに失敗したリンクも、それぞれ区別して記録します。
記事やWordPressの設定を自動で書き換える機能はありません。修正が必要そうなリンクを絞り込み、掲載元とリンク先を見比べながら、自分の手で直すためのツールです。
2. 動作環境とダウンロード
動作環境は、Python 3.11以上が使えるmacOSまたはLinuxです。Windowsには対応していません。同じ検査が二重に起動しないようにする仕組みに、Windowsにはない機能(fcntl)を使っているためです。
検査するのは、自分が所有している、または管理を任されているWordPressサイトに限ってください。
まずターミナルを開きます。macOSなら、「アプリケーション」→「ユーティリティ」→「ターミナル」で起動できます。
Gitが使える場合は、次のコマンドを1行ずつ入力して、ツールを取得します。
git clone https://github.com/k1117n-cmyk/wordpress-link-checker.git
cd wordpress-link-checker
python3 --version
1行目でツールをダウンロードし、2行目でそのフォルダーへ移動します。3行目はPythonのバージョン確認です。「Python 3.12.x」のように、3.11以上の数字が表示されれば準備完了です。3.11より古い場合や、「command not found」などと表示されてコマンドが見つからない場合は、先にPython 3.11以上をインストールしてください。
Gitを使わない場合は、GitHubのページにある緑色の「Code」ボタンから「Download ZIP」を選んでダウンロードできます。解凍したフォルダーの名前はwordpress-link-checker-mainのようになります。ターミナルで、README.mdとbinフォルダーが入っているこのフォルダーへ移動してから作業してください。
たとえば、macOSの「ダウンロード」フォルダーに解凍した場合は、次のように移動します。フォルダー名は、実際の名前に合わせてください。
cd ~/Downloads/wordpress-link-checker-main
python3 --version
この記事は、2026年11月17日更新のバージョン0.2.0に合わせています。ツール自体のバージョンは、次のコマンドで確認できます。先ほどのpython3 --versionはPythonのバージョン確認ですが、こちらはwordpress-link-checkerのバージョン確認です。サイトへのアクセスは行いません。
python3 bin/check_wordpress_links.py --version
3. まずはトップページと記事1〜2本で試す
いきなり全記事を調べるより、最初は少ないページで、設定の仕方と結果の見方に慣れるのがおすすめです。
ここから先のコマンドは、すべてwordpress-link-checkerのフォルダーの中で実行します。まず、ツールに用意されている2種類の設定例を見ておきましょう。
| 設定例のファイル | 掲載元ページの集め方 | 使う場面 |
|---|---|---|
conf/linkcheck_urls_example.json | トップページと、自分で指定した記事のURL | 少数の記事で試す(この章で使用) |
conf/linkcheck_example.json | トップページと、サイトマップに載っているページ | サイト内をまとめて調べる(第6章で使用) |
目的に合わせて、どちらか一方の設定例をコピーして使います。2つの設定ファイルが同時に読み込まれるわけではありません。実行時には、--configで指定した1つの設定ファイルだけが使われます。
設定例をコピーして、実行用のファイルを作る
設定例は直接書き換えず、コピーして実行用のファイルを作ります。cpはファイルをコピーするコマンドで、先に書いたほうがコピー元、後に書いたほうがコピー先です。少数の記事で試す場合は、次のコマンドを実行してください。
cp conf/linkcheck_urls_example.json conf/linkcheck_mysite.json
最初からサイトマップでまとめて調べる場合は、上のコマンドの代わりに、次のコマンドを実行してください。そのあとは第6章へ進み、設定の編集・確認・検査を行います。コピーはここで済んでいるので、第6章のコピー操作は省略できます。少数の記事で試す場合は、このコマンドは必要ありません。
cp conf/linkcheck_example.json conf/linkcheck_mysite_sitemap.json
ここからは、少数の記事で試す場合の説明です。最初のコマンドを実行すると、設定例のconf/linkcheck_urls_example.jsonはそのまま残り、同じ内容のconf/linkcheck_mysite.jsonができます。この章では以降、コピーしてできたconf/linkcheck_mysite.jsonを編集して使います。ファイル名のmysiteは、自分のサイト名に変えなくても構いません。なお、同じ名前のファイルをすでに作ってある場合は、もう一度コピーすると上書きされてしまいます。コピーはせずに、そのファイルを開いてください。
サイトURLと、調べたい記事のURLを記入する
conf/linkcheck_mysite.jsonをテキストエディターで開き、site_id、site_url、additional_urlsの3か所を自分のサイトに合わせて書き換えます。collection(掲載元ページの集め方)はurlsのままにしておきます。こうすると、トップページと指定した記事だけからリンクを集めます。sitemap_urlsも、空の配列[]のままにしてください。
書き換える部分だけを抜き出すと、次のようになります。ファイルにはほかの項目も並んでいますが、最初は設定例の値のままで大丈夫です。ファイル全体をこの内容で置き換えるのではなく、該当する項目の値だけを書き換えてください。
example.comは説明用のURLです。そのまま検査せず、必ず自分のサイトのURLに置き換えてください。
{
"site_id": "mysite",
"site_url": "https://example.com/",
"collection": "urls",
"additional_urls": [
"https://example.com/sample-page/"
]
}
site_idは、結果を保存するフォルダーの名前などに使われる識別名です。半角英数字・ハイフン(-)・アンダースコア(_)を使って自由に決められます。この例ではmysiteとしており、第4章の結果の保存先も、この名前で説明します。設定ファイルの名前とそろえる必要はありません。
site_urlには調べるサイトのトップページのURL、additional_urlsには調べたい記事のURLを書きます。トップページは自動的に掲載元ページに加わるので、additional_urlsに書く必要はありません。
記事を2本以上指定するときは、URLをそれぞれ"で囲み、カンマ(,)で区切って並べます。最後のURLの後ろにはカンマを付けません。
"additional_urls": [
"https://example.com/sample-page/",
"https://example.com/another-page/"
]
設定を確認してから検査する
編集したconf/linkcheck_mysite.jsonを保存したら、次のコマンドで設定に間違いがないかを確認します。--configの後ろには、設定例ではなく、いま編集した実行用のファイルを指定します。
python3 bin/check_wordpress_links.py --config conf/linkcheck_mysite.json --validate-config
このコマンドは設定ファイルをチェックするだけで、サイトへのアクセスも結果ファイルの作成も行いません。エラーが表示された場合は、その内容を見て設定ファイルを直し、もう一度実行してください。よくある原因は、カンマの付け忘れや付けすぎ、"の閉じ忘れです。
問題がなければ、末尾の--validate-configを外して実行し、実際に検査します。
python3 bin/check_wordpress_links.py --config conf/linkcheck_mysite.json
実行中は、画面に###…という記号が少しずつ増えていきます。これは、ツールが動いていることを示す合図です。通信中や再確認の待ち時間にも増え続けますが、何件終わったか、何%進んだかを表すものではありません。
検査が終わると、終了コード(結果を表す数字。意味は第4章で説明します)と、結果の保存先が表示されます。
4. まずは要約で、件数と確認が必要なリンクを見る
結果は、次の場所に保存されます。
reports/linkcheck/<site_id>/<実行日時_一意ID>/
たとえばsite_idをmysiteにした場合は、reports/linkcheck/mysite/の中に、実行するたびに日時入りのフォルダーが作られます。macOSなら、次のコマンドでこのフォルダーをFinderで開けます。
open reports/linkcheck/mysite/
最初に開くのはsummary.md(要約)です。テキストエディターで開けます。
バージョン0.2.0の要約では、冒頭に対象サイト、ツールのバージョン、検査が完了したかどうかが書かれ、続いて「再確認済みリンク切れ」「その他の要確認・未処理」「Amazonリンク(通信せず除外)」の件数が並びます。まずはここで、確認が必要なリンクがあるかどうかを見てください。
その次の「確認が必要なリンク」には、掲載元の記事URL・記事タイトル・リンク文字列・検査URL・最終URL(転送後のURL)・HTTPの応答・判定・理由が、リンクを貼った箇所(掲載箇所)ごとにまとめてあります。
たとえば判定がpendingでHTTPの応答が403なら、アクセスを拒否されたために判定を保留したもので、リンク切れと決まったわけではありません。要約に書かれたURLを見ながら、そのまま掲載元の記事やリンク先をブラウザで確認できます。
ここに詳しく載るのは、最大100か所までです。再確認済みのリンク切れから順に並び、100か所を超えた分は省略されて、省略した件数だけが表示されます。
また、要約の「分類の意味」には、全14分類の意味と確認の仕方も載っています。要約を読むために、READMEを開き直す必要はありません。
リンク切れが0件でも、それだけで「問題なし」とは判断しないでください。掲載元ページを取得できなかったり、時間の上限に達して途中で終わったりしていれば、まだ調べていない部分が残っています。
| ファイル | 確認すること |
|---|---|
summary.md | 完了したかどうか、件数、確認が必要なリンクの詳細(最大100か所)、全14分類の説明、未完了の理由 |
links.tsv | 掲載元、リンク文字列、リンク先、HTTPの判定結果 |
sources.tsv | 掲載元ページを取得できたか、失敗・除外した理由 |
requests.jsonl | アクセスごとの応答、転送や再試行の記録 |
要約で省略された分や、正常だったリンク・除外したリンクも含めたすべての掲載箇所を見たいときは、links.tsvを開きます。
TSVはタブ区切りのテキストファイルで、テキストエディターでも開けますが、表計算ソフトで開くと列ごとに並んで読みやすくなります。
主な列を表にすると、次のようになります。以下は見方を説明するための架空の例で、実際の検査結果ではありません。実際のファイルには、ページのタイトルやリンクの位置、転送後の最終URLなどの列もあります。
| 掲載元URL | リンク文字列 | 検査URL | HTTP | 分類 |
|---|---|---|---|---|
| https://example.com/linux-basics/ | 参考資料 | https://example.org/old-guide/ | 404 | broken |
| https://example.com/linux-basics/ | サポートページ | https://example.org/support/ | 403 | pending |
1行目は、linux-basicsの記事にある「参考資料」というリンクが、再確認でも404だったことを表しています。その記事を開いて「参考資料」のリンクを探し、ブラウザで開けるかを確かめます。
2行目は、リンク先にアクセスを拒否された(403)ため、判定を保留したものです。リンク切れとは限らないので、すぐに削除せず、ブラウザで開けるかを確認してください。
「分類」の列には、主に次のような値が入ります。全14分類の説明は、summary.mdの「分類の意味」で確認できます。
| 分類 | 意味と確認の仕方 |
|---|---|
broken | 再確認しても404・410だった。掲載元の記事とリンク先をブラウザで確認する |
candidate | 初回の検査で404・410だったが、再確認がまだ終わっていない候補 |
pending | 401(認証が必要)・403(アクセス拒否)・429(アクセス過多)などで、判定を保留したもの |
unreachable | DNS・接続エラー・タイムアウト・一時的な障害などで、リンク先に届かなかったもの |
excluded | Amazon関連リンクや除外規則などにより、検査対象から外したもの。Amazon関連リンクには通信せず、除外理由を記録する |
unprocessed | 未処理のもの。robots.txtを取得できなかった場合などの保留もここに入る |
redirected / recovered | 転送先で表示できたもの(redirected)、再試行で表示できたもの(recovered) |
検査の最後に表示される終了コードの意味は、次のとおりです。特に1と2は意味がまったく違うので、要約と合わせて確認してください。
| 終了コード | 意味 |
|---|---|
0 | 設定した範囲の検査が完了し、確認が必要なリンクはなかった |
1 | 検査は完了し、確認が必要なリンクが見つかった |
2 | 検査が最後まで終わらなかった(調べていない範囲がある) |
3 | 設定の誤りなどで、検査を始められなかった |
5. エラーと判定されても、ブラウザでは開けることがあります
自動検査の結果を使ううえで、ぜひ知っておいてほしい点があります。
たとえばYouTubeへのリンクは、このツールではエラーと判定されても、ブラウザでは問題なく表示できることがあります。
そのため、brokenは「再確認しても404・410が返ってきた」という記録として受け取ってください。ページが本当に削除されたとまでは言い切れません。自動検査とブラウザで結果が異なる理由はサイトによってさまざまで、一概には言えません。
エラーが見つかったら、まず掲載元の記事を開き、貼ってあるリンクを実際にクリックしてみてください。目的のページが問題なく表示されれば、修正する必要はありません。
自動検査で「怪しいリンク」と「それを貼っている記事」を絞り込み、最後は自分の目でブラウザで確かめる。そういう使い方を前提にしたツールです。
Amazon関連リンクは、クリック数への影響を避けるためアクセスしません
Amazonアソシエイトのリンクに自動検査でアクセスすると、クリック数の集計に影響する可能性があります。そのため現在の版では、Amazonの直接リンクと既知の短縮リンクを、アクセスする前に検査対象から外しています。
対象は、amazon.co.jpやamazon.comなどのドメインと、そのサブドメインです。短縮リンクのlink.amazon、amzn.to、amzn.asia、amzn.eu、amzn.in、amzn.com、a.coも除外します。商品ごとではなくドメイン単位で除外するため、末尾の商品番号や短縮コードが変わっても通信は行いません。追加の設定も必要ありません。
これらのドメインには、robots.txtを確認するためのアクセスも行いません。ほかのサイトのリンクからAmazonへ転送される場合も、転送先が対象のドメインだと分かった時点で止めます。ただし、自分で用意した中継用のURLは、転送先を確かめるために、その中継URL自体にはアクセスします。中継URLへのアクセスも避けたい場合は、設定のexclude_patternsに、そのURLを除外する規則を追加してください。
除外したリンクも、掲載元と一緒にlinks.tsvに残ります。分類はexcluded、理由は「Amazon関連リンク(クリック集計への影響防止)」です。リンク切れかどうかは判定していないので、気になるものはブラウザで確認してください。また、通信自体を行わないため、requests.jsonlには記録されません。
除外するかどうかは、スクリプトに登録したドメインの一覧で判断しています。新しい短縮サービスや独自の中継URLまで、自動ですべて見分けられるわけではありません。
なお、この無料のPython版には、Amazonリンクだけを別にまとめたレポートや、検査結果をメールで知らせる機能はありません。
6. 慣れてきたら、サイトマップで範囲を広げる
少ないページで使い方がつかめたら、サイトマップを使って、サイト内の記事をまとめて調べられます。
サイトマップ用の設定ファイルの見本を、先ほどとは別の名前でコピーします。
cp conf/linkcheck_example.json conf/linkcheck_mysite_sitemap.json
コピーしたファイルを開き、site_id、site_url、sitemap_urlsの3か所を書き換えます。collectionはsitemapのままにします。
こちらも、書き換える部分だけの抜粋です。example.comは自分のサイトのURLに置き換えてください。
{
"site_id": "mysite",
"site_url": "https://example.com/",
"collection": "sitemap",
"sitemap_urls": [
"https://example.com/wp-sitemap.xml"
]
}
sitemap_urlsには、自分のサイトのサイトマップのURLを書きます。WordPress標準のサイトマップならwp-sitemap.xmlですが、SEOプラグインを使っているとURLが異なることがあります。一度ブラウザで開いて、サイトマップが表示されることを確かめてから指定してください。
設定の確認から検査までの流れは、少数ページのときと同じです。
python3 bin/check_wordpress_links.py --config conf/linkcheck_mysite_sitemap.json --validate-config
python3 bin/check_wordpress_links.py --config conf/linkcheck_mysite_sitemap.json
サイトマップにどのページが含まれるかは、サイトの設定によって違います。たとえば投稿用のpost-sitemap.xmlだけを指定した場合、固定ページは調べられていない可能性があります。summary.mdの収集記録と取得件数を見て、どこまで調べられたかを確認してください。
サイトマップを使えない場合は、公開REST APIを使う方法や、URLの一覧を指定する方法もあります。詳しい設定はREADMEにまとめています。
検査にかかる時間は、ページ数だけでは決まりません
このツールは、相手のサーバーに負担をかけないよう、アクセスを1件ずつ順番に行います。同じ接続先へのアクセスは最低1秒ずつ間を空け、404・410が返ってきたリンクは60秒以上待ってから再確認します。429(アクセス過多)が返ってきた場合も、相手のサーバーの指示(Retry-Afterなど)に従って待ちます。
そのため、所要時間はページ数だけでなく、リンクの数、再確認が必要なリンクの数、相手のサーバーの応答の速さや待ち時間によって大きく変わります。
1回の実行時間の上限は、初期設定で2時間です(待ち時間も含みます)。上限に達すると、その時点で「未完了」として終了します。途中から再開したり、前回との差分だけを調べたりする機能はないため、次に実行するときは最初からやり直しになります。
また、この無料版では、別々に起動したツール同士でアクセスの間隔を調整し合う仕組みがありません。ツールは一度に1つずつ実行し、同じサイトをほかのツールで同時に巡回することも避けてください。
7. 調べられないことと利用条件
このツールが調べるのは、取得した公開ページのHTMLと、リンク先からの応答です。次のようなことはできません。
- JavaScriptによって後から表示されるリンクの検出。
- ログインしないと見られない掲載元ページの検査。
#見出し名のようなページ内リンク(アンカー)の移動先が存在するかの確認。- 記事内のリンクの自動修正。
画像の検査は設定で有効にできますが、初期状態ではオフです。また、robots.txt(クローラーに向けたアクセスのルール)や除外設定を守って動作します。WAF・CAPTCHA・認証などをすり抜けて調べる機能はありません。
無料で使えますが、利用・改変・再配布などの条件は独自の利用許諾で定めています。使う前にLICENSE.txtを確認してください。
また、設定ファイルや結果ファイルには、URLのクエリ(?以降の部分)、サーバーからの応答ヘッダー、パソコン内の保存場所などが記録されます。レポートをブログなどで紹介したり、誰かに渡したりするときは、そのまま公開せず、中身を確認してからにしてください。
まずは気になる記事から点検してみてください
過去の記事を見直すとき、リンクを貼っている記事まで分かる一覧があれば、確認する場所をぐっと絞り込めます。
最初はトップページと代表的な記事をいくつか指定して、レポートから掲載元とリンク先をたどってみてください。ブラウザで確かめて、必要なリンクだけを直す。この流れがつかめたら、サイトマップで範囲を広げていきましょう。
取得方法や設定項目、検査結果の分類の詳しい説明はGitHubにまとめています。
