Umi-OCR User Guide

Umi-OCR is a free, open-source, fully offline OCR application for the desktop. You point it at an image — a screenshot, a file, a pasted picture, or a whole folder — and it extracts the text, with no internet connection, no account, and no per-page fees. It also reads and generates QR codes and barcodes, turns scanned PDFs into searchable documents, and exposes both a command line and an HTTP API so you can automate everything.

This guide covers everything you can do with Umi-OCR: installing it, running your first recognition, every tab and feature, the output formats, and the automation interfaces. Architecture, configuration internals, and deployment live in the companion Admin Guide.

Note

Umi-OCR runs locally on your own machine. Images and documents you recognize never leave your computer — the recognition engine, the HTTP service, and the command-line bridge all operate over the local loopback address only (unless you deliberately open the service to your LAN).

1. Quick Start

1. Download the latest release .7z (or self-extracting .7z.exe) from the releases page.
2. Extract it anywhere. Umi-OCR is portable — there is no installer.
3. Run Umi-OCR.exe.
4. Open the Screenshot OCR tab and press the screenshot shortcut, or paste an image with Ctrl+V.
5. The recognized text appears in the right-hand panel, ready to copy.

Umi-OCR.exe  →  Screenshot OCR tab  →  capture/paste image  →  text extracted instantly

Tip

The very first time you launch Umi-OCR, it picks its interface language automatically from your operating system's language setting. You can change it later under Global Settings → Language.

2. Installation

Umi-OCR is officially distributed as a portable application for Windows 7 x64 and above. There is nothing to install — you unzip and run.

2.1. System Requirements

Note

A Linux build is maintained separately. See the Linux runtime repository for packages and Docker images. The instructions below describe the Windows experience, which is the primary target.

2.2. Download Sources

You can obtain Umi-OCR from any of these mirrors:

• GitHub — https://github.com/hiroi-sora/Umi-OCR/releases/latest
• SourceForge — https://sourceforge.net/projects/umi-ocr
• Lanzou — https://hiroi-sora.lanzoul.com/s/umi-ocr

The release package comes either as a .7z archive or as a self-extracting .7z.exe. The self-extracting form lets you unpack the files on a computer that has no archive utility installed.

2.3. Installation Methods

Portable (recommended)

1. Download the .7z or .7z.exe package.
2. Extract it to a folder of your choice (for example D:\Apps\Umi-OCR).
3. Double-click Umi-OCR.exe to start. No further setup is needed.

Scoop (Windows package manager)

If you use Scoop, add the extras bucket and install one of the two editions:

scoop bucket add extras

Install the edition bundled with the Rapid-OCR engine (better compatibility):

scoop install extras/umi-ocr

Or install the edition bundled with the Paddle-OCR engine (slightly faster):

scoop install extras/umi-ocr-paddle

Warning

Do not install both Scoop editions at once — their shortcuts can overwrite each other. Install one, then add extra OCR engine plugins later if you want to switch engines.

2.4. First Launch

After extraction, click Umi-OCR.exe. The main window opens with a tabbed interface. If anything goes wrong at startup, Umi-OCR shows a native error dialog and writes a log file — note the path it reports, and see Troubleshooting.

3. The Tabbed Interface

Umi-OCR v2 is built from a set of independent tabs. You open only the tabs you need, and you can have several of the same kind open at once.

Two controls sit on the tab bar itself:

• The top-left corner toggles window always-on-top.
• The top-right corner locks the tabs, so you don't close one by accident during daily use.

Tip

If you don't see a tab you want, open it from the navigation/“new tab” control. Tabs are like a favorites menu — open what you use, close what you don't.

4. Everyday Usage

4.1. Screenshot OCR

The Screenshot OCR tab is the fastest way to grab text off your screen.

• Press the screenshot shortcut, then drag a box around the area you want. Umi-OCR recognizes the text immediately.
• Or paste an image you copied elsewhere with Ctrl+V.
• Or drag and drop an image file onto the tab.

The tab is split into two panels:

• Left — image preview. You can select and copy text directly off the rendered image.
• Right — recognition record. You can edit the recognized text, and select and copy multiple past results.

Tip

Press Esc to hide the main window quickly — handy when you use Umi-OCR as a background screenshot tool.

4.2. Batch OCR (many images at once)

The Batch OCR tab recognizes a whole set of local images in a single run.

• Import as many images as you like — there is no limit on the number per run.
• Save the combined results as txt, txtPlain, jsonl, md, or csv (Excel-friendly).
• Optionally have the computer shut down or sleep automatically when the batch finishes.

Tip

For long overnight batches, enable the auto-shutdown option so the machine powers off once recognition completes.

4.3. Batch Document OCR (searchable PDFs)

The Batch Document OCR tab takes scanned documents — primarily PDFs — and produces machine-readable output, including a double-layer searchable PDF that keeps the original page image but adds an invisible, selectable text layer underneath.

You control how each page is handled with the content extraction mode:

You can also restrict which pages are processed (a page range, or an explicit page list) and supply a password for encrypted PDFs.

Important

Document OCR requires Umi-OCR v2.1.4 or newer. Earlier versions do not have this feature.

4.4. QR Codes and Barcodes

The QR Code tab does both directions:

Scan — capture a screenshot, paste, or drag a local image to read codes from it.

• Multiple codes in one image are all detected.
• 19 symbologies are supported: Aztec, Codabar, Code128, Code39, Code93, DataBar, DataBarExpanded, DataMatrix, EAN13, EAN8, ITF, LinearCodes, MatrixCodes, MaxiCode, MicroQRCode, PDF417, QRCode, UPCA, UPCE.

Generate — type text to produce a code image, choosing the format and parameters such as the error-correction level.

4.5. Copying and Editing Results

Across the OCR tabs you can:

• Select text directly on the previewed image (left panel).
• Edit recognized text in the record panel (right panel).
• Select and copy several recognition records at once.

5. Improving Recognition Quality

5.1. Paragraph Merge (layout post-processing)

Raw OCR returns text line by line. Paragraph Merge re-orders and re-joins those lines so the output reads naturally. Choose the scheme that fits your source material:

Tip

For source code or tabular text, pick keep indentation so leading spaces survive. For ordinary prose with multiple columns, the default natural paragraphs scheme gives the most readable result.

5.2. Ignore Regions (skip watermarks and logos)

In Batch OCR you can define ignore regions to exclude unwanted text such as repeating watermarks or logos.

• Open the ignore-region editor in the right-hand settings column of the Batch OCR tab.
• Hold the right mouse button and draw rectangles over the areas to skip.
• Any text block that falls entirely inside an ignore region is discarded.

Warning

Only text blocks completely inside a rectangle are ignored. Draw your rectangles generously — large enough to fully enclose every position the watermark might appear — or stray text will leak through.

5.3. Choosing a Language / Model

The recognition language depends on the OCR engine plugin you have loaded. The bundled PaddleOCR engine ships with model libraries for Simplified Chinese, English, Traditional Chinese, Japanese, Korean, and Cyrillic, switchable in the tab settings. You can install additional engine plugins and switch between them at any time under Global Settings.

Note

Vertical-text recognition needs both a vertical layout scheme and a model library that supports vertical text. See the Admin Guide for engine plugin details.

6. Global Settings

The Global Settings tab adjusts the whole application. Common options:

• Shortcuts / auto-start — add a desktop shortcut or set Umi-OCR to launch with the system, in one click.
• Language — switch the interface language (Simplified/Traditional Chinese, English, Japanese, Portuguese, Russian, Tamil, and more).
• Theme — choose among several light and dark themes.
• Font — adjust the interface font and font size.
• OCR engine — switch between installed OCR engine plugins.
• Renderer — the interface uses GPU-accelerated rendering by default.

Caution

If you see screen flickering, blank panels, or misaligned UI, go to Interface and Appearance → Renderer and try a different rendering scheme, or turn off hardware acceleration. This resolves most display glitches on machines with quirky graphics drivers.

Note

Some HTTP-service options only appear when you enable Advanced mode in Global Settings.

7. Automating Umi-OCR

Umi-OCR can be driven from scripts in two ways: a command line and an HTTP API. Both talk to a running Umi-OCR instance through a local service.

Important

Both interfaces require Umi-OCR's HTTP service to be enabled (it is on by default). In Global Settings, the service host should be set to local only for command-line use. The traffic stays on your machine's loopback interface and never crosses your network card.

7.1. Command Line

The command-line entry point is the main program Umi-OCR.exe. When you run it with arguments and an instance is already running, the arguments are handed to that running instance over the local service.

Get help:

umi-ocr --help

Control the app:

umi-ocr --show       # bring the main window to the foreground
umi-ocr --hide       # hide the main window
umi-ocr --quit       # close the application
umi-ocr --reload     # reload the settings file (v2.1.5+)

Recognize text:

umi-ocr --screenshot               # mouse-drag screenshot, then OCR
umi-ocr --clipboard                # OCR the image on the clipboard
umi-ocr --path "D:/xxx.png"        # OCR a file (or a whole folder, recursively)

You can pass several paths at once; wrap each in quotes and separate them with spaces:

umi-ocr --path "D:/img1.png" "D:/img2.png" "D:/image/test"

Region screenshot (no mouse needed) — add screen= and/or rect=:

umi-ocr --screenshot screen=0 rect=50,100,300,200

Note

The screen and rect parameters are written without a leading --. Supply at least one of them to trigger a region capture; with neither, --screenshot falls back to a mouse-drag capture.

QR codes:

umi-ocr --qrcode_read "D:/xxx.png"                                 # read codes from an image
umi-ocr --qrcode_create "your text" "D:/output.jpeg"               # generate a code
umi-ocr --qrcode_create "your text" "D:/output.jpeg" 128           # generate at 128 px
umi-ocr --qrcode_create "your text" "D:/output.jpeg" 128 256       # width 128, height 256

Send results somewhere:

umi-ocr --screenshot --clip                       # copy result to clipboard
umi-ocr --screenshot --output test.txt            # write result to file (overwrite)
umi-ocr --screenshot --output_append test.txt     # write result to file (append)
umi-ocr --screenshot "-->" test.txt               # "-->" is shorthand for --output
umi-ocr --screenshot "-->>" test.txt              # "-->>" is shorthand for --output_append

Tip

Every flag can be abbreviated to its first few letters — --screenshot and --clipboard can be written --sc and --clipbo. On most systems you can also use the lowercase name and drop the extension: umi-ocr --sc is the same as Umi-OCR.exe --sc.

Warning

Because of how the runtime captures output, the shell redirection operator > and the pipe | may not work. Use --output / --clip to capture results instead. If a script needs the returned text and the command line can't deliver it, use the HTTP /argv endpoint (see the Admin Guide).

7.2. HTTP API (quick taste)

With the HTTP service running (default port 1224), you can recognize an image from any language. For example, query the OCR engine's available options:

curl http://127.0.0.1:1224/api/ocr/get_options

A minimal Python image-OCR call:

import json, requests

resp = requests.post(
    "http://127.0.0.1:1224/api/ocr",
    data=json.dumps({"base64": "<your image base64>", "options": {"data.format": "text"}}),
    headers={"Content-Type": "application/json"},
)
print(json.loads(resp.text)["data"])

The recognized text of the image, line by line.

Note

The full HTTP API — image OCR, the five-step document-OCR workflow, QR code read/generate, and the /argv command bridge, including every parameter and status code — is documented in the Admin Guide.

8. Troubleshooting

Error: [Error] width=0,height=0

Cause: The screenshot captured an empty region (zero width or height). This has been reported on Linux when the screenshot feature receives an invalid capture area (issue #1015).

Solution: Make sure you drag an actual rectangle when capturing. When using rect=, ensure the width and height are greater than zero.

Prevention: Prefer mouse-drag capture, or pass an explicit rect=x,y,w,h with non-zero dimensions.

Error: OCR code:902 ... 向识别器进程传入指令失败，疑似子进程已崩溃 (failed to pass command to recognizer; subprocess likely crashed)

Cause: The OCR engine subprocess crashed or stopped responding (issue #987). Status code 902 means Umi-OCR could not communicate with the recognition engine.

Solution: Restart Umi-OCR so the engine subprocess is re-launched. If it keeps happening, try switching to the other OCR engine (Rapid-OCR vs. Paddle-OCR) under Global Settings, or reduce the image size / batch load.

Prevention: Avoid feeding extremely large images at once; on low-memory machines, lower the engine's image side-length limit.

Error: [Error] 无法创建输出器 (unable to create outputter)

Cause: Document OCR could not create the output file writer for the format you requested (issue #640) — often a permissions or path problem in the output directory.

Solution: Choose a writable output folder, confirm the target file isn't open in another program, and try again.

Prevention: Output to a folder you own (not a system or read-only location).

The command line returns nothing / a script can't read the result

Cause: Output redirection (>, |) is unreliable with the command line, and the calling program may not capture the returned text.

Solution: Use --output "file.txt" or --clip to capture results, or call the HTTP /argv endpoint, which returns the result text in the HTTP response.

Prevention: For programmatic use, prefer the HTTP API over shell redirection.

Umi-OCR won't fully close

Cause: An HTTP client still has an open connection to the service, so the network thread keeps running even after the UI closes.

Solution: Close any program still connected to the HTTP service. If it persists, end the process from Task Manager.

Prevention: Have API clients close their connections when done.

The interface flickers or looks broken

Cause: A graphics-driver incompatibility with the default GPU-accelerated renderer.

Solution: Global Settings → Interface and Appearance → Renderer → try another scheme or disable hardware acceleration.

Prevention: Keep your graphics drivers up to date.

9. Frequently Asked Questions

Q: Is Umi-OCR really free? Yes. The entire project is open-source under the MIT license and completely free to use, modify, and distribute, provided you keep the original copyright and license notice.

Q: Does Umi-OCR need an internet connection? No. It runs fully offline. The bundled OCR engine does all recognition locally, and the command-line/HTTP services use only the local loopback address.

Q: Do I have to install it? No. Umi-OCR is portable — extract the archive and run Umi-OCR.exe. There is no installer and no admin rights required.

Q: Which languages can it recognize? That depends on the OCR engine plugin and its model libraries. The bundled PaddleOCR engine includes Simplified Chinese, English, Traditional Chinese, Japanese, Korean, and Cyrillic. You can add more engine plugins.

Q: What is the difference between the Paddle-OCR and Rapid-OCR editions? Paddle-OCR is slightly faster; Rapid-OCR has broader compatibility. You can install additional plugins and switch engines at any time.

Q: Can it make a scanned PDF searchable? Yes. The Batch Document OCR tab (v2.1.4+) produces a double-layer searchable PDF that keeps the page image and adds a selectable text layer.

Q: Can it read barcodes, not just QR codes? Yes — 19 symbologies including Code128, Code39, EAN13, DataMatrix, PDF417, and more.

Q: How do I change the interface language? Global Settings → Language. On first launch the language is chosen automatically from your system settings.

Q: How do I trigger a region screenshot with a keyboard shortcut? Pair the command line with a hotkey tool such as HotkeysCMD. For example, bind F10 to umi-ocr --screenshot screen=0 rect=50,100,300,200.

Q: Can other computers on my network use the HTTP API? By default the service listens only on localhost. You can switch the service host to “any available address” in Global Settings to allow LAN access — but understand the security trade-offs first (see the Admin Guide).

Q: Where are settings stored? In the UmiOCR-data folder next to the program. See the Admin Guide for the exact files and keys.

Q: Why does the command line need the HTTP service? The command line forwards your instruction to the running Umi-OCR process over the local HTTP service — that is how a second invocation reaches the already-running app. Keep the service enabled (it is by default).

Q: How do I report a bug or request a feature? Open an issue at https://github.com/hiroi-sora/Umi-OCR/issues.

Q: Is there a Linux version? Yes, maintained in a separate repository (Umi-OCR_runtime_linux), including a Docker deployment.

Q: Can I contribute a translation? Yes. Umi-OCR uses Weblate for community localization.

10. Reference

10.1. Command-Line Flags

Note

Advanced flags for power users — --all_pages, --add_page, --del_page, --all_modules, --call_py, --call_qml, --func, --thread — let you invoke arbitrary tab/module functions. They require reading the source to know what to call, and are documented in the Admin Guide.

10.2. Region Screenshot Parameters

10.3. Batch Output Formats

10.4. Supported Code Symbologies (read & generate)

Aztec, Codabar, Code128, Code39, Code93, DataBar, DataBarExpanded, DataMatrix, EAN13, EAN8, ITF, LinearCodes, MatrixCodes, MaxiCode, MicroQRCode, PDF417, QRCode, UPCA, UPCE

10.5. Project Links