Chrome Lens API for Python
English | Русский
An asynchronous Python library and a command-line tool (lens_scan) for Google Lens. It recognises text in images (OCR), translates it, and gives you the word coordinates. It talks to the same Protobuf endpoint as Chrome's Lens overlay.
✨ Features
- OCR from a file, URL, bytes, PIL image or NumPy array. Plain text, blocks (paragraphs, speech bubbles), lines, or words with geometry. Output as text, JSON, JSONL, hOCR or TSV.
- Translation into any language Lens supports.
- Translation drawn onto the image, like Chrome's Lens overlay: the source text is erased and the translation repainted in the original colours, angle and line box. Handles right-to-left scripts and vertical Japanese, with a manga mode for comic pages.
- Warm daemon.
lens_scanhands each command to a background process that is already running, so an image takes about 0.4 s instead of 3 s. It starts by itself. - ShareX integration: one command sets up two hotkeys, a fast one and one that always works.
- Python API with retries, backoff, fallback keys and endpoints, and a concurrency limit.
- Region queries: re-read a small area at native resolution.
- Proxy support (HTTP, HTTPS, SOCKS) and builds for Windows, Linux and macOS.
📦 Install
| Method | Command | Notes |
|---|---|---|
| Homebrew (macOS, Linux) | brew install bropines/tap/lens-scan |
No Python needed. Apple Silicon and x86_64 Linux. |
| uv, Windows | irm https://raw.githubusercontent.com/bropines/chrome-lens-py/main/scripts/install-uv.ps1 | iex |
No Python needed: uv brings its own. No executable of ours, so nothing for antivirus to flag. |
| uv, Linux / macOS | curl -fsSL https://raw.githubusercontent.com/bropines/chrome-lens-py/main/scripts/install-uv.sh | sh |
Same. |
| Standalone, Windows | irm https://raw.githubusercontent.com/bropines/chrome-lens-py/main/scripts/install.ps1 | iex |
No Python needed. Fastest start (~0.2 s). If your antivirus quarantines the compiled lens_scan.exe, the installer switches to the portable build, which runs through python.org's signed python.exe. Force it with $env:LENS_SCAN_FLAVOR = 'portable'. |
| Standalone, Linux / macOS | curl -fsSL https://raw.githubusercontent.com/bropines/chrome-lens-py/main/scripts/install.sh | sh |
No Python needed. Verifies the SHA-256 of the download. |
| Scoop (Windows) | scoop bucket add lens https://github.com/bropines/chrome-lens-py then scoop install lens-scan |
Or lens-scan-portable. |
| pip | pip install "chrome-lens-py[clipboard]" |
Your own Python, 3.9 or newer. The extra enables --sharex. |
| Docker | docker run -d -p 127.0.0.1:8765:8765 -e LENS_TOKEN=change-me ghcr.io/bropines/chrome-lens-py |
Runs the HTTP server. LENS_TOKEN is required. |
Check it with lens_scan --version: it prints which copy runs. Checksums, attestations, version pinning and more: docs/install.md.
🚀 Quick start
lens_scan image.png # OCR, language auto-detected
lens_scan image.png -t en # OCR + translate to English
lens_scan image.png ja -t ru -sx # recognise Japanese, translate, copy to the clipboard
lens_scan image.png -t en -to out.png # also save the image with the translation drawn on it
lens_scan page.png ja -t en -to out.png --manga # manga page: vertical Japanese, bubbles
lens_scan scans/ --format jsonl > out.jsonl # a whole folder, one JSON object per image
lens_scan --setup-sharex --mode both -t ru # ShareX: Ctrl+O and Ctrl+Shift+O (Windows)
From Python (every call is async):
import asyncio
from chrome_lens_py import LensAPI
async def main():
async with LensAPI() as api:
result = await api.process_image(
"image.png", ocr_language="ja", target_translation_language="en"
)
print(result["ocr_text"])
print(result["translated_text"])
asyncio.run(main())
Result data goes to stdout and everything else to stderr, so lens_scan img.png > out.txt holds only the text. Exit code: 0 all images succeeded, 1 all failed, 2 some failed.
📚 Documentation
| Page | What is in it |
|---|---|
| docs/cli.md | Every option, output formats, exit codes, config file, LENS_* variables and their precedence. |
| docs/api.md | LensAPI: constructor, process_image, process_region, result fields, exceptions, examples. |
| docs/rendering.md | Drawing the translation onto the image: vertical text, erase modes, outline, manga mode, fonts. |
| docs/daemon.md | Fast mode and the warm daemon, the login service, the HTTP API, the security model. |
| docs/install.md | All install methods, checksums and provenance, pinning a version, the portable build, Docker. |
| docs/sharex.md | ShareX setup: the two hotkeys, uploader mode, manual setup, troubleshooting. |
| CHANGELOG.md | What changed in each release. |
❤️ Support & Acknowledgments
- OWOCR: Greatly inspired by and based on OWOCR. Thank you to them for their research into Protobuf and OCR implementation.
- Chrome Lens OCR: For the original implementation and ideas that formed the basis of this library. The update with SHAREX support was originally tested and added by me to chrome-lens-ocr, thanks for the initial implementation and ideas.
- AI Collaboration: A significant portion of the v3.0 code, including the architectural refactor, asynchronous implementation, and Protobuf integration, was developed in collaboration with an advanced AI assistant.
- GOOGLE: For the convenient and high-quality Lens technology.
- Support the Author: If you find this library useful, you can support the author - Boosty
Star History
Disclaimer
This project is intended for educational and experimental purposes only. Use of Google's services must comply with their Terms of Service. The author is not responsible for any misuse of this software.
1 maintainer
Metadata
1 maintainer
Release files for chrome-lens-py 3.7.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| chrome_lens_py-3.7.1.tar.gz | 202.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| chrome_lens_py-3.7.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 394.9 kB
Release files / chrome_lens_py-3.7.1.tar.gz
| Download URL | chrome_lens_py-3.7.1.tar.gz |
|---|---|
| Size | 202.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a53d959332ac768370eb2203065d8c146d2532a2bfa6b09fe2f9d603a419d0ee
|
|
BLAKE2b-256 checksum How to use checksums |
118adfa2cce0d2fd74485dc7ff457e3976bff381afe305b4ccc0668679fb4ced
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / chrome_lens_py-3.7.1-py3-none-any.whl
| Download URL | chrome_lens_py-3.7.1-py3-none-any.whl |
|---|---|
| Size | 192.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d746bc4e3688da12b4d7563d776d337b76d1fd78de55f72ad535d19e497738f7
|
|
BLAKE2b-256 checksum How to use checksums |
1db88dea7ba2861a7c61feedacb65856bab517e69f920564af4de6b14d3b6ec8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency log
