Windows 環境での ndlocr-cli 環境構築マニュアル（CPU実行版）

◆Windows11+WSL2によるndlocr-cli実行環境構築マニュアル (2025年9月版)

第0章. はじめに

この手順書は、Windows 11 PC上で、国立国会図書館が開発した高性能OCRエンジン ndlocr-cli をCPUで動かすための、環境構築手順を記したものです。
※GPU実行版の手順を作成中です。別途アップロードしますので、GPUで動かしたい方はその公開をお待ちください。

以下で公開されている内容を元に作成しました。

• NDLOCR ver.2の公開について
• NDLラボ公式GitHubアカウント

ただ、公式のインストール手順や README.md ファイルは、現在の開発状況と異なっており、公式手順通りに進めても環境を完成させることができませんでした。AIとの対話を通じて3日間の悪戦苦闘の末に環境構築に成功した工程をまとめたのがこの手順書です。

• 本手順書は、ndlocr-cli の main 開発ブランチ（2025年9月時点の最新版）をベースにしています。
• 元々GPUで実行するように作られている物を、GPUを使わないで実行するように修正してあります。GPU実行でOKの場合は不要な手順が含まれます。（Step 8: CPU実行のためのソースコード・設定ファイル修正）
• もしエラーが発生した場合は、諦めずに、この手順書全体とエラーメッセージをAI（ChatGPT, Geminiなど）に提示し、解決策を相談してみてください。

第1章：Windowsでの事前準備

まず、Windows上で必要なソフトウェアのインストールを完了させましょう。

1. WSL2 (Ubuntu) のインストール

Windows上でLinux環境を動かすための公式機能「WSL2」をインストールします。

ステップ1.1：Microsoft StoreからUbuntu 20.04 LTSをインストールする

1. Windowsのスタートメニューから「Microsoft Store」を起動します。
2. 検索バーで「Ubuntu 20.04 LTS」と検索します。（LTS版が長期サポートで安定しています）
3. 「入手」または「インストール」ボタンをクリックして、インストールを開始します。
4. インストールが完了すると、PCの再起動を求められる場合があります。その場合は指示に従って再起動してください。

ステップ1.2：Ubuntuの初期セットアップ（最も重要なステップ）

1. インストールが完了したら、必ずスタートメニューから「Ubuntu」を一度起動してください。
2. 初回起動時に、ターミナルウィンドウが開き、Installing, this may take a few minutes…と表示されます。
3. Enter new UNIX username: と表示されたら、あなたのユーザー名（例: fhf）を入力してEnterキーを押します。
   （注：ユーザー名は、必ず半角のアルファベット小文字、数字、アンダースコア、ハイフンのみで構成し、32文字以内にするのが安全です。）
4. New password: と表示されたら、パスワードを入力します。（画面に入力した文字は表示されません）
5. Retype new password: で、もう一度同じパスワードを入力します。
6. Installation successful!と表示され、fhf@…:~$ というプロンプトが表示されれば、初期セットアップは完了です。

exit

wsl --shutdown

wsl --export Ubuntu D:\wsl_backup\ubuntu-fresh.tar

wsl --unregister Ubuntu

wsl --import Ubuntu <インストール先フォルダ> <バックアップファイルのパス>

ubuntu config --default-user <ユーザー名>

2. Git for Windows のインストール

ソースコードをダウンロードするために必要なツール「Git」をインストールします。

1. Webブラウザで公式サイトのダウンロードページにアクセスします: https://git-scm.com/downloads/win
2. 表示されたページで、「Standalone Installer」セクションにある「64-bit Git for Windows Setup.」のリンクをクリックし、インストーラーをダウンロードします。（ほとんどの現代的なWindows PCはこのバージョンです）
3. ダウンロードしたインストーラーをダブルクリックして実行します。
4. インストール中の設定は、すべてデフォルトのまま「Next」をクリックし続けて問題ありません。最後まで進めてインストールを完了してください。

3. テキストエディタの準備

後の手順でソースコードを編集するために、高機能なテキストエディタを準備しておくことを推奨します。（Windows標準のメモ帳は非推奨です）

• 推奨エディタ例: Visual Studio Code や Notepad++ など

第2章：WSL (Ubuntu) での環境構築

【重要】ここからの作業は、すべてWSL2のUbuntuターミナルで行います。
第1章のWSLインストールで使ったPowerShellの画面はもう使いませんので、閉じてしまって問題ありません。

Ubuntuターミナルの起動方法

1. Windowsのスタートメニューを開き、「ubuntu」と入力して検索します。
2. 表示された「Ubuntu」という名前のアプリケーションをクリックして起動します。
3. 黒い背景に白い文字の画面が立ち上がれば成功です。これがUbuntuターミナルです。
   $ マークの右側にカーソルが点滅していることを確認し、以下のコマンドを一行ずつ、コピー＆ペーストして、Enterキーで実行していきましょう。

Step 1: プロジェクトソースの準備

まず、ndlocr-cli 本体と、関連ライブラリ KyTea のソースコードをダウンロードします。

# 1. ホームディレクトリに移動します
cd ~
# 2. 作業用のディレクトリを作成し、そこに移動します
mkdir projects
cd projects
# 3. ndlocr-cli のソースコードをダウンロードします
git clone https://github.com/ndl-lab/ndlocr_cli.git
# 4. KyTea のソースコードをダウンロードします
git clone https://github.com/neubig/kytea.git
# 5. ndlocr_cli ディレクトリに移動します
cd ndlocr_cli
# 6. サブモジュール（追加部品）を互換性のある正しいバージョンでダウンロードします
git submodule update --init --recursive

Step 2: WSL2 (Ubuntu) の基礎環境構築

プログラムのビルドに必要な基本的なツールと、このプロジェクトの心臓部であるPython 3.10をインストールします。

sudoコマンドの実行時にwslアカウントのパスワード入力を求められます。「第1章 1. WSL2 (Ubuntu) のインストール」で設定したパスワードを入力してください。

また、インストールが進むと、途中で続行かキャンセルか確認されます。続行なのでEnterキーを押してください。

# 1. システムを最新の状態に更新します
sudo apt update
sudo apt upgrade -y
# 2. ビルドとファイル展開に必要なツールをまとめてインストールします
# swig, autoconf などはKyTeaのビルドに必須です
sudo apt install -y build-essential cmake git swig autoconf automake libtool unzip wget
# 3. Python 3.10をインストールするための準備をします
sudo add-apt-repository ppa:deadsnakes/ppa
# 4. Python 3.10本体と、関連ツールをインストールします
sudo apt install -y python3.10 python3.10-venv python3.10-dev

Step 3: 学習済みモデルの自動配置

以降、多くのコマンドは ~/projects/ndlocr_cli ディレクトリで実行します。

ndlocr-cliの動作には、複数の学習済みモデルファイルが必要です。以下のコマンドは、配置先のディレクトリを作成した上で、必要なモデルを公式サイトから一つずつダウンロードし、それぞれ正しいディレクトリに直接配置します。

# ndlocr_cli ディレクトリにいることを確認
cd ~/projects/ndlocr_cli

# 1. モデルの配置先ディレクトリを事前に作成します
mkdir -p submodules/separate_pages_mmdet/models
mkdir -p submodules/ndl_layout/models
mkdir -p submodules/text_recognition_lightning/models/rf_author
mkdir -p submodules/text_recognition_lightning/models/rf_title

# 2. 各モデルをダウンロードし、所定の場所に配置します
# ページ分割モデル
wget https://lab.ndl.go.jp/dataset/ndlocr_v2/separate_pages_mmdet/epoch_180.pth -O ./submodules/separate_pages_mmdet/models/epoch_180.pth
# レイアウト抽出モデル
wget https://lab.ndl.go.jp/dataset/ndlocr_v2/ndl_layout/ndl_retrainmodel.pth -O ./submodules/ndl_layout/models/ndl_retrainmodel.pth
# 文字認識モデル
wget https://lab.ndl.go.jp/dataset/ndlocr_v2/text_recognition_lightning/resnet-orient2.ckpt -O ./submodules/text_recognition_lightning/models/resnet-orient2.ckpt

# 3. 著者名・タイトル認識用モデルをダウンロードし、所定の場所に配置します
wget https://lab.ndl.go.jp/dataset/ndlocr_v2/text_recognition_lightning/rf_author/model.pkl -O ./submodules/text_recognition_lightning/models/rf_author/model.pkl
wget https://lab.ndl.go.jp/dataset/ndlocr_v2/text_recognition_lightning/rf_title/model.pkl -O ./submodules/text_recognition_lightning/models/rf_title/model.pkl

echo "モデルファイルの配置が完了しました。"

Step 4: KyTea (C++本体) のビルド

C++で書かれたKyTeaライブラリ（エンジン本体）をビルドし、システムにインストールします。

# 1. KyTeaのソースディレクトリに移動します
cd ~/projects/kytea/

# 2. ビルド設定ファイルを生成します
autoreconf -i

# 3. ビルド設定を実行します
./configure

# 4. コンパイルします（少し時間がかかります）
make

# 5. システムにインストールします（パスワードを求められます）
sudo make install

# 6. 【最重要】インストールしたライブラリをシステムに認識させます
sudo ldconfig

Step 5: Python仮想環境の構築とライブラリのインストール

ここが最も繊細なパートです。ndlocr_cli ディレクトリの中に、このプロジェクト専用のPython環境を構築し、数々のライブラリを「相互依存関係で問題が発生しないバージョンの組み合わせ」でインストールします。

# 1. プロジェクトのホームディレクトリに戻ります
cd ~/projects/ndlocr_cli

# 2. Python 3.10で、この場所専用の仮想環境(.venv)を作成します
python3.10 -m venv .venv

# 3. 作成した仮想環境を有効化します（プロンプトの先頭に (.venv) と表示されます）
source .venv/bin/activate

# 4. pipを更新し、互換性のある古いバージョン(24.1未満)に固定します
pip install --upgrade pip
pip install "pip<24.1"

Step 6: requirements.txt を編集し、ビルドエラーの原因となる2行を無効化（コメントアウト）

編集方法について：Windowsのテキストエディタが便利です

WSL内の nano コマンドでも可能ですが、Windows上の使い慣れたテキストエディタで行うと簡単です。

【重要】Windowsのエディタを使う場合の注意点
ファイルを保存する際は、必ず改行コードを LF (Linux形式) に設定してください。Notepad++の場合、メニューの [ 編集 ] → [ 改行コード変換 ] → [ Unix (LF) ] を選択してから保存します。

修正対象ファイル: ~/projects/ndlocr_cli/requirements.txt

エクスプローラーのアドレスバーに \\wsl$ と入力するとUbuntuのフォルダが表示されます。
この傘下にのフォルダに ndl_ocr が仮想的に格納されています。

修正対象のファイルは、同フォルダ傘下の Ubuntu/home/<あなたのユーザー名>/projects/ndlocr_cli/requirements.txt です。

テキストエディタで開いて、以下の行を探してコメントアウトしてください。

▼ 修正前 (Before)

...
opencv-python==4.5.1.48
...
scikit-image==0.16.2
...

▼ 修正後 (After)　 #で対象行をコメントアウトしてファイルを保存。

...
#opencv-python==4.5.1.48
...
#scikit-image==0.16.2
...

Step.7：ライブラリのインストール

requirements.txt の修正後、以下のコマンドをこの順番通りに実行してください。

途中のBuilding wheel for mmcv-full (setup.py) の処理にかなり時間がかかりますが(10分くらい？)、気長に完了をお待ちください。

# 相互依存関係で問題が発生しないバージョンの組み合わせでライブラリをインストールします
pip install wheel scikit-build
pip install torch==1.11.0+cpu torchvision==0.12.0+cpu -f https://download.pytorch.org/whl/cpu/torch_stable.html
pip install mmcv-full==1.4.5 -f https://download.openmmlab.com/mmcv/dist/cpu/torch1.11.0/index.html --no-cache-dir
pip install mmdet==2.19.0
pip install numpy==1.23.1
pip install torchmetrics==0.7.3 --no-dependencies
pip install -r requirements.txt --no-build-isolation
pip install scikit-image --no-dependencies
pip install lazy_loader tifffile imageio networkx --no-dependencies
pip install kytea==0.1.7

実行ログに以下のエラーが表示されるかもしれませんが、このエラーは全く問題ないので無視してください。
（numpy==1.23.1でないと相互依存問題をクリアできないことを確認済みです）

以下の黄色いログも全く問題ないので無視してください。

Step 8: CPU実行のためのソースコード・設定ファイル修正

ダウンロードしたソースコードは、GPUでの動作を前提としているため、CPUで正しく動作させるには、以下の4つのファイルを修正する必要があります。
Step 6のときと同様に、それぞれのフォルダの対象のファイルを開いて指示通り修正してください。
（テキストエディタを使った編集方法は Step 6 の注意書き「 編集方法について」を参照してください）

修正対象ファイル1: ~/projects/ndlocr_cli/submodules/separate_pages_mmdet/inference_divide.py

▼ 修正前 (Before)

# 8行目あたり
import cv2
import numpy as np
import mmcv
from mmdet.apis import (inference_detector, init_detector)
# ...
# 58行目あたり
    def load(self, config: str, checkpoint: str, device: str):
        self.model = init_detector(config, checkpoint, device)

▼ 修正後 (After)

# 8行目あたり
import cv2
import numpy as np
import mmcv
import torch # <--- この行を追加
from mmdet.apis import (inference_detector, init_detector)
# ...
# 58行目あたり
    def load(self, config: str, checkpoint: str, device: str):
        self.model = init_detector(config, checkpoint, device=torch.device('cpu')) # <--- この行を修正

修正対象ファイル2: ~/projects/ndlocr_cli/submodules/ndl_layout/tools/process_textblock.py

▼ 修正前 (Before)

# 11行目あたり
from typing import List
from lxml import etree as ET
import mmcv
from mmdet.apis import (inference_detector, init_detector)
# ...
# 627行目あたり
class InferencerWithCLI:
    def init(self, conf_dict):
        config = conf_dict['config_path']
        checkpoint = conf_dict['checkpoint_path']
        device = conf_dict['device']
        self.detector = LayoutDetector(config, checkpoint, device)

▼ 修正後 (After)

# 11行目あたり
from typing import List
from lxml import etree as ET
import torch # <--- この行を追加
import mmcv
from mmdet.apis import (inference_detector, init_detector)
# ...
# 627行目あたり
class InferencerWithCLI:
    def __init__(self, conf_dict):
        config = conf_dict['config_path']
        checkpoint = conf_dict['checkpoint_path']
        device = torch.device('cpu') # <--- この行を修正
        self.detector = LayoutDetector(config, checkpoint, device)

修正対象ファイル3: ~/projects/ndlocr_cli/submodules/text_recognition_lightning/configs/trainer/default.yaml

▼ 修正前 (Before)

# 9行目
accelerator: gpu

▼ 修正後 (After)

# 9行目
accelerator: cpu # <--- この行を修正

修正対象ファイル4: ~/projects/ndlocr_cli/submodules/text_recognition_lightning/configs/infer.yaml

▼ 修正前 (Before)

# 9行目
  - measure_time.yaml

▼ 修正後 (After)　 #で対象行をコメントアウト

# 9行目
  # - measure_time.yaml

第3章：実行編 – 動作確認

すべての準備が整いました。最後のステップです。

1. テスト用ディレクトリと画像の準備

1. プロジェクト内部にテスト用ディレクトリ一式を作成

プログラムはOCR対象の画像の配置先として input/img/ という特殊なディレクトリ構造を要求します。以下のコマンドで準備しましょう。

cd ~/projects/ndlocr_cli
mkdir -p ocr_test_local/input/img
mkdir -p ocr_test_local/output

2. テストしたい画像を準備します

Windowsのエクスプローラーでアドレスバーに \\wsl$ と入力し、Enterを押します。
表示された Ubuntu\home\<ユーザー名>\projects\ndlocr_cli\ocr_test_local\input\img\ を開き、その中に画像ファイルをコピーしてください。

2. 実行コマンドと出力結果の確認

ndlocr-cli は、目的に応じて出力形式を変えることができます。ここでは2つの主要な実行方法を紹介します。

1.画像から文字情報だけを抽出したい場合の基本的なコマンド

▼ 実行コマンド

# Ubuntuターミナルで、仮想環境が有効な状態で実行します
cd ~/projects/ndlocr_cli

# Pythonに現在の場所をパッケージのルートとして教えます
export PYTHONPATH=.

# 実行！
python main.py infer ocr_test_local/input ocr_test_local/output

▼ 出力されるデータ
コマンドが成功すると、~/projects/ndlocr_cli/ocr_test_local/ の中に output_YYYYMMDD… という名前のフォルダが生成されます。
その中の input/txt フォルダに、以下のようなプレーンテキストファイルが出力されます。

• test01_main.txt: 本文のテキスト
• test01_ruby.txt: ルビ情報を含むテキスト
• test01_cap.txt: キャプションや柱などのテキスト

2.文字情報に加えて座標情報も出力する場合のコマンド

別途後続のプログラムを作成して、元の画像の上に検索可能な透明テキストを重ねたPDFファイルを作成したい場合、文字の座標情報が必要です。以下のコマンドは、その座標情報を含むXMLファイルを追加で出力します。

▼ 実行コマンド
–save_xml というオプションを末尾に追加するだけです。

# Ubuntuターミナルで、仮想環境が有効な状態で実行します
cd ~/projects/ndlocr_cli

# Pythonに現在の場所をパッケージのルートとして教えます
export PYTHONPATH=.

# 実行！（--save_xml オプションを追加）
python main.py infer ocr_test_local/input ocr_test_local/output --save_xml

▼ 出力されるデータ
上記のテキストファイル群に加えて、output_…/input/xml というフォルダが作成され、その中に座標情報を含む input.sorted.xml のようなXMLファイルが出力されます。
このXMLファイルが、透明テキスト付きPDFを作成するための重要な「素材」となります。

Average processing time (total) などのログが表示され、エラーなくコマンドが終了すれば、環境構築は成功です！

環境構築、お疲れ様でした！

補足：ndl_ocrを使いたい時のコンソールの立ち上げ方

Ubuntuターミナルを起動したら、以下の3つのコマンドを順番に実行してください。

# ステップ1：プロジェクトのホームディレクトリに移動する
cd ~/projects/ndlocr_cli

# ステップ2：Pythonの専用環境（仮想環境）を有効にする
source .venv/bin/activate

# ステップ3：Pythonにプロジェクトの場所を教える
export PYTHONPATH=.

これで、あなたのターミナルはndlocr-cliをいつでも実行できる準備万端の状態になります。
プロンプト（カーソルの左側の表示）の先頭に (.venv) という文字が表示されていれば、正しく準備ができたサインです。