System dependencies
Miru shells out to, or links against, six external tools. Missing any of them does not
stop the app booting; it stops one kind of file from being processed, and the
upload lands in a failed state with an error the uploader can see.
libvips — required
Every image passes through libvips: decode, auto-orient, resize to the three variant sizes, and write out without metadata. There is no fallback. Without libvips, Miru starts and no photograph will ever process.
# Debian / Ubuntu
apt install libvips-dev
# macOS
brew install vips
heif-convert — required for HEIC
Photographs from any recent iPhone are HEIC. Miru does not ask libvips to
decode them; it converts them to JPEG first with heif-convert, which comes
from libheif's examples package. Depending on a separately-installed binary
rather than on how libvips happened to be compiled is the more predictable of
the two options — a distribution's libvips may or may not have libheif linked
in, and finding out involves reading vips -l.
apt install libheif-examples # Debian / Ubuntu
brew install libheif # macOS
Without it, HEIC uploads fail while JPEG works perfectly — a confusing symptom if you are not expecting it, and the ordinary case for anyone using the iOS app.
Check with:
heif-convert --help
A licensing note for self-hosters. HEVC is covered by patents, and distributing a build with an HEVC encoder has licensing implications that vary by jurisdiction. Miru only ever decodes HEIC; it writes JPEG. That is a narrower position than encoding, but it is not legal advice, and if you are distributing binaries you should look into it rather than take this paragraph as settled.
FFmpeg — required for video
Transcoding to H.264, generating HLS segments for streaming, extracting the thumbnail frame, and reading duration, resolution and frame rate.
apt install ffmpeg # Debian / Ubuntu
brew install ffmpeg # macOS
Without it, video uploads fail and images are unaffected.
exiftool and dcraw — required for RAW
RAW files are handled in two steps, and the second is a fallback.
- exiftool extracts the JPEG preview that almost every camera embeds in its RAW files. This is fast and gives an accurate rendering, because the camera made it.
- dcraw develops the RAW itself, for the files that have no usable embedded preview.
apt install libimage-exiftool-perl dcraw
brew install exiftool dcraw
Without exiftool, RAW uploads fail. Without dcraw, most RAW files still work — the ones with no embedded preview do not.
The original RAW is always preserved regardless, and always downloadable.
Tesseract — required for text-inside-photos search
Miru runs OCR against a stripped, display-sized JPEG after an upload completes. The recognized text stays private in the media record and makes signs, menus, receipts, and notes discoverable from the owner's search page. Existing library items can be queued from that page; each file is an independent retryable job.
apt install tesseract-ocr # Debian / Ubuntu
brew install tesseract # macOS
Without Tesseract, uploads and every other search filter keep working, but OCR jobs retry and photographs do not become searchable by the words inside them.
Checking what you have
vips --version
ffmpeg -version | head -1
exiftool -ver
dcraw -h 2>&1 | head -1
tesseract --version | head -1
In a container
The production image installs all of these. If you are building your own, the relevant lines are:
RUN apt-get update && apt-get install -y --no-install-recommends \
libvips42 ffmpeg libimage-exiftool-perl dcraw libheif-examples tesseract-ocr \
&& rm -rf /var/lib/apt/lists/*
Note libvips42 rather than libvips-dev — the runtime image needs the shared
library, not the headers.
This list is not advisory. Every one of these is reached by a System.cmd/3
call somewhere in the media pipeline. Missing media codecs fail the matching
upload type; missing Tesseract leaves only the OCR index incomplete.