English | 中文

Turn scanned PDFs into searchable PDFs — text you can select, copy and search — with the OCR engine built into macOS, running on GitHub's macOS runners. It is fast, runs entirely on the runner, and is especially good at Chinese, Japanese and Korean.

There are two ways to use it:

• In a workflow: one step that converts a file or a folder.
• As your own OCR service: drop a PDF into a private repository, get the searchable version back a few minutes later.

jobs:
  ocr:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v7
      - uses: muhac/pdf-ocr-action@v1
        with:
          input: scans
          output: searchable
          language: eng
      - uses: actions/upload-artifact@v7
        with:
          name: searchable-pdfs
          path: searchable

When input is a folder, a file that cannot be processed does not stop the others; the step fails at the end and the good results are still written.

Languages. Common codes: eng, chi_sim, chi_tra, jpn, kor, fra, deu, spa, ita, por, rus. The full list has about 30. Each PDF is read in one language, but Latin text inside a Chinese, Japanese or Korean page is still recognized.

Several languages at once. When input is a folder, PDFs in a subfolder named after a language code are read in that language, and the output keeps the subfolder: scans/chi_tra/a.pdf becomes searchable/chi_tra/a.pdf. PDFs directly in the folder use language. Other subfolders are ignored.

Your PDFs live in a private repository that only you can see. Your copy of this repository does the OCR and never stores them.

you ── add PDF ──▶ private repository: inbox/
                        │
                        ▼
                 your copy of pdf-ocr-action (macOS runner)
                        │
                        ▼
                   private repository: done/   (failed/ if a file cannot be processed)

1. Service repository. Fork this repository, then open the fork's Actions tab and enable workflows.
2. Documents repository. Pick any private repository of yours, new or existing. Nothing has to be installed in it.
3. Connect them. Create a fine-grained personal access token limited to the documents repository with Contents: Read and write. In the service repository, under Settings → Secrets and variables → Actions, add these secrets:

Folders may be nested, for example scans/todo. The service downloads only these three folders, so the rest of the documents repository can hold anything else, such as an organized library, without slowing it down. To change the language from the default eng, add a repository variable OCR_LANGUAGE, for example chi_sim.

Add PDFs to the inbox folder, by git push or by uploading on github.com. Then start the OCR workflow from the service repository's Actions tab, or from a terminal:

gh workflow run ocr.yml --repo your-name/pdf-ocr-action

A few minutes later each PDF appears in the done folder under the same name and is removed from the inbox. Files that cannot be processed are moved to the failed folder.

PDFs directly in the inbox are read in the default language. For another language, put them in a subfolder named after its code, such as inbox/chi_sim/ or inbox/chi_tra/; the result appears in the same subfolder of the done folder.

To have the service start by itself whenever a PDF arrives, add this workflow to the documents repository as .github/workflows/ocr.yml:

on:
  push:
    branches: [main]
    paths: ["inbox/**"]
  release:
    types: [published]

jobs:
  trigger:
    runs-on: ubuntu-latest
    steps:
      - uses: muhac/pdf-ocr-action/trigger@v1
        with:
          service: your-name/pdf-ocr-action
          token: ${{ secrets.SERVICE_TOKEN }}

SERVICE_TOKEN is a second fine-grained token, limited to the service repository with Actions: Read and write, saved as a secret in the documents repository. The trigger also accepts language and mode. With branch, the service works on that branch of the documents repository instead of its default branch: results are committed there, so a pull request can be squash-merged to keep the originals out of the default branch's history. The branch name is masked in the service's public log, but choose names that say nothing about the documents anyway. The release part is only needed for large files, described next; branches keeps the tag of a new release from starting a second run.

After saving, the service sends an ocr-done event to your documents repository. With the workflow below in the documents repository, every batch of results is compared with the originals: page count, bookmarks, and page by page how much text was found against how much ink is on the page. Pages that are inked like text but carry little text are counted as suspect; if more than a tenth of a book is suspect, the check fails. The report is posted on the pull request (or in the run summary for the default branch), and the commit gets an ocr-check status.

name: Check OCR

on:
  repository_dispatch:
    types: [ocr-done]

permissions:
  contents: read
  pull-requests: write
  statuses: write

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.event.client_payload.commit }}
          fetch-depth: 2
          filter: blob:none
          sparse-checkout: done
      - id: check
        uses: muhac/pdf-ocr-action/check@v1
        with:
          claude-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}  # optional
      # then post ${{ steps.check.outputs.report }} where you like

Run it in a private repository only: the report names your files.

The optional claude-token shows each flagged page to Claude next to the text OCR found on it. Claude calls the page blank, an illustration, or text that OCR captured or missed, and adds a one-line note in the book's language; the verdicts go into a collapsible table, and Claude's full answer into the run log. Pages go to Claude ten at a time; max-pages caps how many (0 reviews them all). language: zh writes the report in Chinese. It takes a subscription token made with claude setup-token, never an API key: the check strips API keys from Claude's environment and discards any answer not made with the subscription. Claude Code is pinned, because --bare, which ignores subscription tokens, is to become the default for claude -p. Page images are sent to Anthropic, and the review uses your subscription's allowance; max-pages caps it.

Git does not accept files over 100 MB. Send those through a release of the documents repository instead, which allows up to 2 GB per file:

1. Create a release in the documents repository, attach the PDF and publish it.
2. Run the service, unless it starts automatically.
3. The service attaches two files to the same release: book.ocr.pdf, the searchable result, and book.ocr.log, whose first line is done or failed.

• A PDF is processed when there is no .ocr.log next to it. Delete the log to have the PDF processed again; add one yourself to have a PDF left alone.
• To choose the language, put its code alone on the first line of the release description, for example chi_tra.
• GitHub drops non-Latin characters from attachment names (测试.pdf is stored as default.pdf), so put the real name in the release title.
• Draft releases are ignored.

• PDFs are stored only in your private repository. They are processed on a GitHub-hosted runner that is discarded after the job. No third-party OCR service is involved.
• The service repository is public and so are its logs. The service only logs counts, such as [1/3] done, never file names, folder names, release names or the name of your documents repository. That is why those settings are secrets.
• Anyone who obtains STORAGE_TOKEN can read your documents. Limit it to the one repository and give it an expiry date.
• GitHub Actions use is subject to GitHub's terms. macOS runners are free for public repositories and billed by the minute for private ones. The service setup is meant for light personal use.

• macOS runners only (Apple's OCR is not available elsewhere). Tested on macos-15 and macos-26; macos-14 is not supported. Prefer macos-15: on macos-26, Traditional Chinese pages lost much of their text in both livetext and accurate modes (measured on a 450-page book), while Simplified Chinese was unaffected.
• One language per PDF.
• The service reads PDFs directly inside the inbox folder and its language subfolders, nothing deeper. Files larger than 100 MB have to go through a release.

On a Mac with uv and brew install tesseract:

OCR_LANGUAGE=chi_sim scripts/ocr.sh scan.pdf searchable.pdf
tests/run.sh   # end-to-end tests

Built on OCRmyPDF and OCRmyPDF-AppleOCR. Licensed under MIT.

把扫描版 PDF 变成可搜索的 PDF——文字可以选中、复制、搜索。使用 macOS 自带的文字识别引擎，在 GitHub 的 macOS runner 上运行。速度快，全程在 runner 本机完成，中文、日文、韩文的识别效果尤其好。

有两种用法：

• 在 workflow 里调用：一个步骤，转换一个文件或一个文件夹。
• 搭建自己的 OCR 服务：把 PDF 放进私有仓库，几分钟后拿回可搜索的版本。

jobs:
  ocr:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v7
      - uses: muhac/pdf-ocr-action@v1
        with:
          input: scans
          output: searchable
          language: chi_sim
      - uses: actions/upload-artifact@v7
        with:
          name: searchable-pdfs
          path: searchable

input 是文件夹时，某个文件处理失败不会影响其他文件；该步骤最后会报失败，但成功的结果照常输出。

语言。 常用代码：chi_sim（简体中文）、chi_tra（繁体中文）、eng、jpn、kor、fra、deu、spa、rus。完整列表约 30 种。每份 PDF 按一种语言识别，不过中日韩文页面里夹杂的英文和数字仍然能识别。

同时处理多种语言。 input 是文件夹时，放在以语言代码命名的子文件夹里的 PDF 会按该语言识别，输出保持同样的子文件夹：scans/chi_tra/a.pdf 对应 searchable/chi_tra/a.pdf。直接放在文件夹里的 PDF 使用 language。其他子文件夹会被忽略。

PDF 存在只有你能看到的私有仓库里，你自己的这份 pdf-ocr-action 负责识别，不保存任何文件。

你 ── 放入 PDF ──▶ 私有仓库：inbox/
                       │
                       ▼
                你自己的 pdf-ocr-action（macOS runner）
                       │
                       ▼
                  私有仓库：done/   （处理不了的文件进 failed/）

1. 服务仓库。 Fork 本仓库，然后在 fork 的 Actions 页启用 workflow。
2. 文档仓库。 任选一个你自己的私有仓库，新建或现有的都行，里面不需要安装任何东西。
3. 把两者连起来。 创建一个 fine-grained personal access token，只授权文档仓库，权限选 Contents: Read and write。在服务仓库的 Settings → Secrets and variables → Actions 里添加以下 secret：

文件夹可以是多级路径，例如 scans/todo。服务只下载这三个文件夹，文档仓库里的其他内容（比如整理好的资料库）不会被下载，也不会拖慢它。默认语言是 eng，要改的话添加一个仓库 variable OCR_LANGUAGE，例如 chi_sim。

把 PDF 放进收件文件夹，用 git push 或在 github.com 网页上传都行。然后到服务仓库的 Actions 页运行 OCR workflow，或者在终端执行：

gh workflow run ocr.yml --repo 你的用户名/pdf-ocr-action

几分钟后，同名文件会出现在结果文件夹里，收件文件夹里的原件被移除。处理不了的文件会被移到失败文件夹。

直接放在收件文件夹里的 PDF 按默认语言识别。要用其他语言，就放进以语言代码命名的子文件夹，例如 inbox/chi_sim/ 或 inbox/chi_tra/；结果会出现在结果文件夹的同名子文件夹里。

想让服务在 PDF 到达时自动开始，就在文档仓库里添加这个 workflow，保存为 .github/workflows/ocr.yml：

on:
  push:
    branches: [main]
    paths: ["inbox/**"]
  release:
    types: [published]

jobs:
  trigger:
    runs-on: ubuntu-latest
    steps:
      - uses: muhac/pdf-ocr-action/trigger@v1
        with:
          service: 你的用户名/pdf-ocr-action
          token: ${{ secrets.SERVICE_TOKEN }}

SERVICE_TOKEN 是第二个 fine-grained token，只授权服务仓库，权限选 Actions: Read and write，作为 secret 保存在文档仓库里。trigger 还接受 language 和 mode 两个参数。加上 branch 参数，服务会在文档仓库的那个分支上工作而不是默认分支：结果提交到该分支，之后用 squash 合并 PR，原件就不会进入默认分支的历史。分支名在服务的公开日志里会被遮盖，但仍建议分支名不要透露文档内容。release 那部分只在处理大文件时需要，见下一节；branches 是为了避免新 Release 的标签再触发一次运行。

服务存完结果后，会给文档仓库发一个 ocr-done 事件。在文档仓库里加上下面这个 workflow，每批结果都会和原件对比：页数、书签，以及逐页比较识别出的文字量和页面上的墨量。墨量像正文页、文字却很少的页面算作"可疑"；一本书超过十分之一的页面可疑，检查就判为失败。报告会发在 PR 上（默认分支则写在运行摘要里），提交上会多一个 ocr-check 状态。

name: Check OCR

on:
  repository_dispatch:
    types: [ocr-done]

permissions:
  contents: read
  pull-requests: write
  statuses: write

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.event.client_payload.commit }}
          fetch-depth: 2
          filter: blob:none
          sparse-checkout: done
      - id: check
        uses: muhac/pdf-ocr-action/check@v1
        with:
          claude-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}  # 可选
      # 然后把 ${{ steps.check.outputs.report }} 发到你想要的地方

只在私有仓库里运行：报告里有你的文件名。

可选的 claude-token 会把每个被标记的页面连同识别出的文字一起交给 Claude 对照。Claude 判断这一页是空白、插图，还是文字已识别或漏识别，并用书本身的语言写一句说明；判断放在报告里一个可折叠的表格中，完整回答打印在运行日志里。页面每 10 页一批交给 Claude，max-pages 限制总页数（0 表示全部审阅）。language: zh 让报告用中文。它只接受 claude setup-token 生成的订阅 token，不用 API key：检查会把 API key 从 Claude 的环境里去掉，不是用订阅完成的回答一律丢弃。Claude Code 的版本是固定的，因为会忽略订阅 token 的 --bare 模式将来会成为 claude -p 的默认行为。页面图片会发送给 Anthropic，用量算在你的订阅额度里，可以用 max-pages 限制。

Git 不接受超过 100 MB 的文件。这类文件改用文档仓库的 Release 传递，单个文件最大 2 GB：

1. 在文档仓库新建一个 Release，把 PDF 作为附件上传并发布。
2. 运行服务；配置了自动触发的话不用手动运行。
3. 服务会往同一个 Release 里添加两个文件：book.ocr.pdf 是可搜索的结果，book.ocr.log 的第一行是 done 或 failed。

• 一个 PDF 旁边没有对应的 .ocr.log 时才会被处理。删掉日志就会重新处理；自己放一个日志进去，这个 PDF 就不会被处理。
• 要指定语言，把语言代码单独写在 Release 说明的第一行，例如 chi_tra。
• GitHub 会去掉附件文件名里的非拉丁字符（测试.pdf 会被存成 default.pdf），所以真正的名字请写在 Release 的标题里。
• 草稿状态的 Release 不会被处理。

• PDF 只存放在你的私有仓库。处理在 GitHub 托管的 runner 上进行，任务结束后 runner 即销毁。不经过任何第三方 OCR 服务。
• 服务仓库是公开的，它的日志也是公开的。服务只记录数量（如 [1/3] done），不记录文件名、文件夹名、Release 名，也不记录文档仓库的名字。这些配置之所以放在 secret 里，就是这个原因。
• 拿到 STORAGE_TOKEN 的人可以读取你的文档。请只授权那一个仓库，并设置过期时间。
• 使用 GitHub Actions 须遵守 GitHub 的条款。macOS runner 对公开仓库免费，对私有仓库按分钟计费。服务这种用法适合个人少量使用。

• 只能在 macOS runner 上运行（Apple 的文字识别在其他系统上不可用）。已在 macos-15 和 macos-26 上测试通过；不支持 macos-14。 建议用 macos-15：在 macos-26 上，繁体中文页面在 livetext 和 accurate 两种模式下都会丢失大量文字（用一本 450 页的书实测），简体中文不受影响。
• 每份 PDF 只能按一种语言识别。
• 服务只读取收件文件夹及其语言子文件夹里的 PDF，不读更深的层级。超过 100 MB 的文件需要通过 Release 传递。

在装有 uv 并执行过 brew install tesseract 的 Mac 上：

OCR_LANGUAGE=chi_sim scripts/ocr.sh scan.pdf searchable.pdf
tests/run.sh   # 端到端测试

Read the rest on GitHub