MacOCR promises that a failed read leaves your clipboard alone
Get any text on your screen into your clipboard.
At a glance
- What is it?
- schappim/macOCR is a small Swift tool that turns a drag of the mouse into text on your clipboard, using Apple's Vision framework with no account and no upload. What makes it interesting is not the recognition. It is how carefully the clipboard contract is specified, and how plainly the distribution gap is stated.
- Who is it for?
- macOCR fits anyone who reads text out of things they cannot select, screenshots, video stills, PDFs that refuse to copy, conference badges, parcel labels, and it is honest enough that you can predict what it will do to your clipboard before you run it. Check four things.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 72 days ago.
- What is it written in?
- Mainly Swift, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- schappim/macOCR2,444 ★ · +6
| Repository | 2026-09-30 | 2026-11-15 |
|---|---|---|
| schappim/macOCR | 2.4k | 2.4k |
6 Stars in the last 46 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
A failed read leaves the clipboard alone, and that promise appears twice
The interaction is one word and one gesture: run the command, your cursor becomes a crosshair, drag a box, and whatever was inside it is now on your clipboard. The subtlety is in what happens when that does not work. Two separate places in the document state it. If nothing is read, the tool prints nothing and leaves your clipboard untouched, and the reason given is the good one: a misjudged selection costs you a second attempt rather than whatever you had copied earlier. And if you press escape to cancel the selection, it copies nothing and again leaves your clipboard alone. For a tool whose entire purpose is to overwrite the clipboard on every successful run, those two guarantees are the difference between a utility and a hazard, and the second one is worth noting because the default also reads barcodes, so a single drag can replace your clipboard with a URL rather than prose without asking.
Standard output and the clipboard are deliberately different surfaces
There is a rule stated in bold and then explained, and it is the design decision that makes the tool scriptable. Whatever standard output looks like, the clipboard gets plain text. That is the stated point of the tool, and there is an option to suppress the clipboard write entirely for the cases where it is not wanted. So the machine interface and the human interface are separate: request structured output and the program prints structured data for a script to consume, while a human pasting into a document still gets clean text rather than markup. The other half of the contract is the opposite failure, and it is equally deliberate. Structured output is described as going to standard output instead of plain text, and the clipboard write is described as happening even then. In other words the tool will not guess which one you meant, and the only way to get one without the other is to ask for it.
The language flag is a different feature on each of three system generations
Recognition works out of the box for English and a flag switches it, and then the flag's own availability depends on the system version. On the most recent generation the tool reports that the machine recognises around thirty languages, naming Japanese, Korean, Russian, Ukrainian, Thai, Vietnamese, Arabic, and Turkish among them. The two generations before that recognise eight: English, French, Italian, German, Spanish, Portuguese, and the two Chinese scripts. And on the oldest supported system the flag does not exist at all, so the tool reads English regardless. That is three different capabilities behind one option, and the document is explicit that choosing a language requires a named minimum system version. What it does not do is print a fixed list, because a fixed list would be wrong twice, and instead the tool asks the system what it can do and reports the answer.
Asking for Japanese does not stop it reading English
One behaviour in the language section is easy to read past and changes what a flag means. English stays in the list as a fallback when you select another language, and the reason given is a concrete case: a mostly Japanese screenshot with an English address in it still reads both. That is a good default for the tool's actual use case, where a screenshot of a foreign page routinely contains a Latin address, a product code, or a menu word from the desktop it was taken on. It also means the flag is not a filter. Anyone using it to guarantee that output contains only one language, which is what a translation pipeline or a locale-specific parser would want, gets something else. The document does not offer a way to exclude the fallback, and it does not pretend to; the sentence is there, and the behaviour is what it is.
The binaries are not notarised, and the manual install moves a file into a system directory
The distribution section is candid in a way most projects are not. Released binaries are described as ad-hoc signed rather than notarised, and the consequence is stated: the system may refuse to run a downloaded copy. The fix is given as one command that removes the quarantine attribute from the installed file once:
xattr -d com.apple.quarantine /usr/local/bin/ocrThe manual install path is three commands per architecture, and the third one moves the binary into a system binary directory as root, with a separate variant for each of the two processor architectures. So the route that avoids a package manager is also the route that bypasses the system's provenance check and writes to a shared location as root. The document's own preference is the other one: use the package manager route, partly because the built-in update command only works there.
The permission is granted to whoever launches the tool, not to you
The first-run section contains one instruction and one warning, and the warning is the useful one. The tool takes a screenshot, so the first run triggers a screen recording permission request, and you grant it and try again. But if you are calling the command from a launcher rather than from a terminal, the document says the prompt belongs to that application, and you have to approve it there as well. Two named launchers are given as examples, plus the system automation app. That is a platform behaviour rather than a bug, because the permission attaches to the process doing the capturing, and the project's own framing is that this is what a first run looks like. It is also the single most likely thing to waste an afternoon on, since the symptom is a tool that silently produces nothing.
Three flags exist to ask the system what it can do
The option list is organised into groups, and three entries in it share a purpose that is worth naming separately. One lists the recognition languages this machine can actually handle. One lists every barcode symbology this machine can read. One prints the version and the architecture of the binary that is running. Two more accept a restricted list, one for recognition languages and one for symbologies, and both take a compact syntax such as a comma separated pair. The shared purpose is that the capability comes from the operating system's framework rather than from the program, so the program cannot know it ahead of time and hardcoding a table would be a lie on some machines. That design choice explains the whole list. It also explains why the tool reports a fixed region as an option with four numbers, why it can render a PDF page at a chosen resolution, and why it will read an image from standard input when you pass a single dash.
Editorial conclusion
macOCR fits anyone who reads text out of things they cannot select, screenshots, video stills, PDFs that refuse to copy, conference badges, parcel labels, and it is honest enough that you can predict what it will do to your clipboard before you run it. Check four things. Which install route you take, because the released binaries are not notarised and the manual route moves a file into a system directory as root, while the package manager route is the one that supports in-place upgrades. Whether your macOS version supports the language flag at all, because the capability changes across three generations. Whether you are launching it from a terminal or from a launcher, because the screen recording permission is granted to whichever process started it. And what you want on the clipboard versus on standard output, since those are deliberately different things.
Frequently asked questions
What does macOCR do?
You run it, your cursor becomes a crosshair, you drag a box over anything on screen, and the text inside it is printed and copied to your clipboard. By default it reads both the text and the payload of any QR code or barcode in the region, in the order they appear. It also reads the clipboard image, an image file, or a PDF page by page.
Does macOCR send anything to a server?
No. Everything runs on your Mac using Apple's Vision framework. No API keys, no uploads, no account, and it works offline.
What happens to my clipboard if macOCR reads nothing?
Nothing. It prints nothing and leaves your clipboard untouched, so a misjudged selection costs you a second attempt rather than your previous copy. Cancelling the selection with escape also copies nothing and leaves the clipboard alone.
Can I use macOCR in a script?
Yes. Structured JSON goes to standard output while the clipboard still receives plain text, and there is an option to suppress the clipboard write entirely for scripts. You can also read an image from standard input, capture a fixed region instead of dragging, and restrict which languages or barcode symbologies to look for.
Why will macOCR not run after I download it?
Released binaries are ad-hoc signed rather than notarised, so the system may refuse them. The project says to clear the quarantine attribute once on the installed file. The recommended alternative is the package manager route, which is also the only route where the built-in update command works.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/schappim-macocr)Star history chart for your README
[](https://hysenlabs.com/projects/schappim-macocr)Was this useful?