Local AI OCR: offline image and PDF text extraction on your own machine

What Local AI OCR is for: documents that will not leave the machine

Local AI OCR is a desktop OCR application, and the name of the approach is the main selling point. The repository description calls it a local, offline (after initial setup), portable OCR tool that processes images and PDF files using DeepSeek-OCR-2 running directly on the machine. Once the setup script has finished, the software needs no network connection at all.

That constraint is what makes the project interesting for a particular kind of user. Contracts, invoices, internal reports, medical paperwork or anything else where a document should not be uploaded to a third-party endpoint can be processed on the workstation instead. The README states the privacy position plainly: no connection is needed and nothing is transmitted anywhere.

The audience is also visible in the interface itself. The README is written in Vietnamese with an English version at README_en.md, and the application chooses its interface language automatically based on whether the machine has the Vietnamese browsers Cốc Cốc or Zalỏ installed. The supported output languages are broader than the interface: Vietnamese, English, Chinese, Japanese and others.

The input side covers the formats you actually get from a scanner or a phone camera, namely .png, .jpg, .webp, .heic and .heif images plus .pdf documents. The output side is Word. Those two ends, image in and .docx out, define what the application is for.

Three extraction modes and the difference layout makes

The README describes three processing modes, and the choice is really a choice about how much structure survives the extraction.

The Markdown document mode extracts text and tries to keep the layout, including tables. The Free OCR mode also extracts text and is described as keeping the layout better than the Standard OCR mode. The Standard OCR mode extracts text and keeps the layout poorly. The README advises keeping the default, since the default is described as the best option, so the modes are more of a fallback ladder than a menu of equal choices.

Layout preservation is the feature that separates this from character-level recognition. When a page contains a table or a chart, the output is meant to arrive as structured Markdown that can be pasted into Word and still read as a table. The README also describes automatic image extraction, where charts and pictures inside a document are detected and pulled out so they can be inserted straight into the result.

The result panel has two views. One shows the raw text, the other, labelled as the pretty result, shows formatted output. The application switches to the pretty view automatically when OCR finishes. From the pretty view, copying keeps the formatting, so the text can be pasted into Word or another editor with the structure intact. There is also a separate button that writes the output directly to a .docx file next to the clipboard option.

Setup on Windows and Linux, and the 6.67 GB download it triggers

Installation starts from the Releases section of the repository. You download a .zip on Windows or a .tar.gz on Linux, extract it, and run the setup script for your platform. On Windows that script is:

env_setup.cmd

On Linux you open a terminal in the extracted folder, make the shell scripts executable and run the Linux setup script:

chmod +x *.sh
./env_setup_linux.sh

The setup step is where the size of the project becomes obvious. The README states that the script downloads heavy AI weight files of 6.67 GB. Combined with the roughly 11 GB of free disk space the requirements list, this is a one-time cost rather than a per-image cost, and it is why the README calls the tool offline after the initial setup: the model is local from that point on, so nothing needs to be fetched again.

The README is explicit that a first run always takes some time, because the AI model has to be loaded into memory. After the first processing job finishes, the application waits five minutes and then releases the model automatically. A button labelled for releasing the AI model frees the memory immediately when you want it back, which is the sensible move if you are between documents and need the RAM or VRAM for something else.

The Python stack under the window

The requirements file describes the whole dependency set, and it reads like a vision-language pipeline wrapped in a desktop shell:

# src/main.py
PySide6==6.11.1

huggingface-hub
hf_xet==1.5.1

transformers==4.46.3
tokenizers==0.20.3
img2pdf==0.6.3
einops==0.8.2
easydict==1.13
addict==2.4.0
numpy==2.5.0

pillow==12.2.0
pillow-heif==1.4.0
PyMuPDF==1.27.2.3
Markdown==3.10.2

pypandoc_binary==1.17
python-docx==1.2.0

The interface is PySide6, pinned to 6.11.1. The model side comes from transformers at 4.46.3 with tokenizers at 0.20.3, plus huggingface-hub and hf_xet for fetching the weights. einops, easydict and addict handle the tensor and config plumbing, numpy does the array work.

Document handling is more interesting than the model side. PyMuPDF at 1.27.2.3 covers the PDF path, and pillow-heif at 1.4.0 plus pillow at 12.2.0 cover the image formats including HEIC. img2pdf appears alongside them, which is the usual way to turn image pages into a PDF for the model to read.

The output stack explains the Word export and the formatted view. Markdown at 3.10.2 handles the intermediate representation, pypandoc_binary at 1.17 provides the conversion engine, and python-docx at 1.2.0 writes the .docx file. The pinned versions are precise, which is worth noting for anyone planning to reproduce the environment.

The repository topics include vllm, but the requirements file does not list it. The README does not explain the inference backend either, so treat the topic tag as a signal rather than a documented dependency.

Queue handling, page selection and the drag-and-drop ordering flaw

Batch work is handled by a queue rather than a single-file dialog. You add images or a PDF to the processing queue, and for a PDF you pick the page range to include, a selection the README says is available for files of two pages or more. There is also a control to clear the queue entirely.

The queue is where the tool's most visible defect sits. The README states plainly that dragging and dropping files may not preserve the file order, calls this a limitation of the software, and says there is currently no way to work around it. That is an unusual admission to make in a feature list, and it is practical to know about: if you drop twenty scanned pages and they arrive in a different order, the assembled document will be wrong in a way that is easy to miss and tedious to fix.

The workaround is procedural rather than technical. Add files one at a time, or use the add control for each page and confirm the order in the queue before pressing start. The README also warns that even with DeepSeek-OCR-2 having very high accuracy, results should still be checked, particularly for important documents. A tool that is generally right still needs a review pass when the output is a signed contract.

GPU expectations, the 8 GB VRAM rule and the CPU fallback

The recommended requirements are Windows 10 or later, or Linux, a CPU with at least four cores and eight threads, at least 16 GB of RAM, roughly 11 GB of free disk, and an Nvidia GPU with at least 8 GB of VRAM.

The README is careful about the edges of that list. You can run the software without meeting the requirements, and it works even without a GPU at all, but it will be much slower. It also notes that the software will attempt to use the GPU even when available VRAM falls short of the recommendation, so a machine with a smaller card may appear to work and then behave badly.

The troubleshooting section is where the practical detail sits. If the application is using CPU and RAM while ignoring the Nvidia GPU, check the driver version in the Nvidia Control Panel: version 531 or newer is required. If the setup script fails at step [1/6], the likely cause is Windows 10 or 11 on the 21H2 release, and the suggested fix is to upgrade to at least 22H2. For any GPU-related error, the documented escape hatch is the CPU-only launcher:

run.cmd
run_cpu-only.cmd

The same pair exists on Linux, where the GPU script is the default and the other one forces CPU execution:

./run_linux.sh
./run_linux_cpu-only.sh

Local AI OCR against hosted OCR services

The alternative is the category the project is defined against: sending the page to a hosted OCR service. The difference in approach is where the model lives and what happens to the document. A hosted service runs recognition on infrastructure you do not control, transmits every page off the machine, and typically meters the work per page. Local AI OCR moves the model onto the workstation, so the document never leaves it and the cost is a one-time download rather than a per-page charge.

The second difference is the kind of recognition. A conventional OCR engine matches character shapes in a rasterised image. A vision-language model reads the page as a document, which is what lets this tool emit Markdown with real tables, keep a reading order across columns, and pull charts out as images instead of losing them. That is a genuine advantage on scans that contain structure, and it is why the Free OCR and Markdown modes exist as separate settings.

The cost of that approach is the profile of the tool. A 6.67 GB weight download, 11 GB of disk, 16 GB of RAM and a preference for an 8 GB VRAM card put Local AI OCR in the category of workstation application rather than something you run on a small server or a thin client. For a business with a scanning pipeline and a dozen pages a day, a hosted service is the more economical shape. For documents that must not leave the building, the local route is the one that works.

Licence, release history and the cost of the 3.0 line

The project is released under the Apache License 2.0. As a matter of reading the licence text, that is a permissive grant which allows use in commercial and closed products, with the usual obligations to keep the copyright and licence notices with the copies you distribute and to mark changes you make.

The release history shows a project that has moved quickly but only recently reached a major version. Version 2.3.1 was tagged on 2026-04-25, version 2.4.0 on 2026-06-28 as a feature update, and version 3.0.0 on 2026-07-05 as a major update. The last push to the repository was on 2026-07-05, the same day as the 3.0.0 tag, and the default branch is master rather than main.

Two smaller items are worth knowing before you commit to it. The repository keeps a README_dev.md next to the user-facing documentation, so developer-facing notes exist separately. It also ships make_release.cmd and make_release_linux.sh, so the release packaging is scripted and reproducible on both platforms. The demo/ directory holds sample inputs, a PDF and two images, which is a fast way to see what the output looks like before you point it at anything of your own.

Editorial conclusion

Adopt Local AI OCR when documents must stay on the machine, when the source is a scanned PDF or an image rather than a text file, and when the output has to be a Word file with tables and images intact. Do not adopt it for a server-side batch pipeline or for a machine without a discrete GPU, since the CPU path is much slower and the first setup downloads 6.67 GB of weights. Verify first that the NVIDIA driver on the machine is version 531 or newer, that you have about 11 GB of free disk and 16 GB of RAM, and that a single test page round-trips correctly before you queue a large batch.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. th1nhhdk/local_ai_ocr on GitHub