Moondream: a 2B vision language model you can run locally

What Moondream is for, and who it is aimed at

Moondream is an open source vision language model released under Apache-2.0 by m87 Labs. The README describes it as "a tiny vision language model that kicks ass and runs anywhere", which is marketing language, but the underlying claim is specific: image understanding at a parameter count small enough to fit on constrained hardware. The repository ships two variants. Moondream 2B is the primary model at 2 billion parameters, positioned for general-purpose image understanding including captioning, visual question answering and object detection. Moondream 0.5B is a 500 million parameter model the README describes as "specifically optimized as a distillation target for edge devices".

The audience follows from that split. If you are building a product that needs to answer questions about a user-supplied image, describe a photo, or locate objects inside one, and you cannot send that image to a hosted API, Moondream is aimed at you. The 0.5B variant targets a narrower reader: someone deploying to a device where 2B parameters will not fit, who accepts a distillation target rather than a full model. The README does not state accuracy numbers for either variant, so the size difference is documented but the quality difference is not.

How the repository is laid out and what that implies

The top-level tree is a Python project with a small surface area. There is a moondream/ package directory, a tests/ directory, a requirements.txt, and a set of runnable entry points: sample.py, batch_generate_example.py, gradio_demo.py and webcam_gradio_demo.py. There are also examples/, notebooks/ and recipes/ directories, plus an assets/ folder holding the demo images the README references.

That layout tells you something the prose does not. The presence of a webcam demo and a Gradio demo alongside a plain sample script suggests the intended path is interactive first: get a model loaded, point it at an image or a camera, and see output. The batch_generate_example.py file points at the other use case, running the model over many inputs rather than one. The recipes/ and notebooks/ directories are where you would look for task-specific flows, though the README does not describe what is inside them.

The requirements.txt pins exact versions: torch==2.8.0, transformers==4.56.1, accelerate==1.10.1, Pillow-SIMD==9.5.0.post2, pyvips==2.2.3 and pyvips-binary==8.16.0, with gradio==4.38.1 for the demos. Two entries are marked as needed for running evals: datasets==3.2.0 and editdistance==0.8.1. Pinned dependencies are a real benefit for reproducibility and a real cost for maintenance, because a torch upgrade in your environment means reconciling with this file. Note also the pyvips pair. It pulls in a native library stack, which is the most likely source of install friction on a fresh machine.

Installing Moondream and running a first image query

The README is explicit that it does not contain install instructions. Under "How to use" it states: "Moondream can be run locally, or in the cloud. Please refer to the Getting Started page for details." That page is linked at https://moondream.ai/c/docs/quickstart. This is the single most important thing to understand before adopting the project: the GitHub repository is the source and the examples, while the documentation lives on the project website. If your workflow requires that a dependency be installable and documented entirely from its repository, Moondream does not meet that bar today.

The repository does give you the dependency set, which is the part you can act on without the website. The requirements.txt file is the declared environment for the Python package:

pip install -r requirements.txt

That installs the pinned versions listed above, including torch 2.8.0 and the pyvips native bindings. Expect this to be the slow step, and expect it to be where a pyvips build failure surfaces if your system lacks the underlying library. The README does not document troubleshooting for that case.

Once the environment is in place, the repository's own entry point for a single run is sample.py. The README does not print its invocation, so the honest statement is that the file exists at the repository root and the quickstart page is where the project documents how to call it. The README does, however, show the shape of the interaction through its examples table. Given an image of a girl at a table, the documented query and response are:

What is the girl doing?
The girl is sitting at a table and eating a large hamburger.

And on the same image, a second query returns a short factual answer rather than a sentence: "What color is the girl's hair?" yields "The girl's hair is white." That contrast matters. The model responds in whatever register the question implies, which is useful for captioning and awkward if you need a fixed output schema. The second README example, a server rack photo, shows the opposite failure mode: asked "What is this?" the model produces a long paragraph about racks, cables and a nearby couch, well past what the question required.

For an interactive check, the repository includes gradio_demo.py and webcam_gradio_demo.py. These are the files to run if you want to see the model work before wiring it into anything. The README does not document ports or flags for them, so read the files themselves before launching.

The output-length problem in the README's own examples

The two README examples disagree about verbosity, and that disagreement is worth taking seriously rather than treating as a demo quirk. On the hamburger image, both answers are short. On the server rack image, the answer to "What is this?" runs to several sentences and volunteers details nobody asked for: the power supply arrangement, the cabling, the carpet, the couch. The follow-up question, "What is behind the stand?", gets a clean four-word answer.

The pattern suggests the model's verbosity tracks how open-ended the question is. A narrow question gets a narrow answer. A broad question gets a paragraph. For captioning that is fine, even desirable. For anything where you parse the output programmatically, it is a constraint you have to design around, either by asking narrow questions or by post-processing. The README does not document a length control, a max-token setting, or a structured output mode, so there is no documented lever to pull. That is a limitation of the documentation as much as of the model, but it is a limitation either way.

Where Moondream is the wrong tool

The clearest case against Moondream is when your task is pure object detection. The README lists object detection among the 2B model's capabilities, but if all you need is bounding boxes on a fixed set of classes, a dedicated detector is smaller, faster and easier to evaluate. Moondream's value is that one model handles captioning, question answering and detection together. If you only need one of those, you are paying for capability you do not use.

The second case is deployment environments that demand a documented, self-contained install. The README defers to the website, and the README does not document rollback, version pinning strategy for model weights, or how to obtain the weights themselves. There is no release list in the repository metadata, so there is no changelog to consult when something changes. If your organization requires a documented upgrade path before a dependency is approved, Moondream does not provide one in the repository.

The third case is accuracy-sensitive work on the 0.5B variant. The README calls it a distillation target for edge devices, which is a statement about its purpose, not a claim of parity with the 2B model. Nothing in the README gives a quality comparison between the two. Choosing 0.5B to save memory without measuring the quality drop on your own data is a decision the documentation does not support you in making.

Moondream versus YOLO for detection work

The comparison people reach for is against YOLO, and the difference is architectural rather than a matter of which is better. YOLO-style detectors are trained for one job: given an image, produce boxes and class labels. They are small, fast, and their output format is fixed, which makes them trivial to evaluate and to slot into a pipeline. Moondream is a vision language model, so detection is one behavior among several, expressed through the same text interface as captioning and question answering.

That means the trade runs in both directions. If you need boxes and nothing else, a dedicated detector gives you a narrower, more predictable contract. If you need to ask "what is the girl doing" and "what color is her hair" and "is there a rack in this photo" against the same model, Moondream covers ground a detector cannot, because those are language questions, not classification questions. The cost is that the output is text, so you own the parsing, and the README's own examples show the output length is not fixed.

A practical reading: use Moondream when the task is genuinely multi-modal across question types, and use a detector when the task is boxes. The README does not benchmark either path, so the decision rests on your output contract rather than on published numbers.

Maintenance, licensing and what the repository does not tell you

The last push to the repository was on 2026-04-20, five months before today. The repository is not archived, but there is no release list in the metadata, so there is no version history to inspect and no changelog to read. Treat the project as one where you track the main branch and the website documentation, not a tagged release cadence. The requirements.txt pins torch, transformers and accelerate to exact versions, which means any environment upgrade is a deliberate reconciliation step rather than a routine one. Budget for that.

On licensing, the repository carries Apache-2.0. That is a permissive license with an explicit patent grant, and it is the same license family most teams already have approved. Two things the README does not resolve: the license file governs the code in this repository, and the README does not state the license terms for the model weights themselves. If you are shipping a product, confirm the weight licensing separately rather than assuming the repository's Apache-2.0 covers it. That is a question for your own review, not something the README answers.

The dependency on a website for documentation is the maintenance cost people underestimate. When the quickstart page changes, your install instructions change, and nothing in the repository records the previous state. There is no rollback documented.

Who should adopt Moondream

Adopt it if your problem is image understanding on hardware where a large VLM will not fit, and if you are comfortable with the project's documentation living on moondream.ai rather than in the repository. The 2B model is the default choice; the 0.5B model is for edge deployment where 2B is not an option, and you should measure the quality difference yourself before committing to it.

Do not adopt it if you need a documented install path inside the repository, if you need a release history to plan upgrades against, if you need fixed-format output without writing your own parsing layer, or if your task is plain object detection. In those cases a dedicated detector or a larger hosted model will serve you better, and the README gives you no evidence to the contrary.

The first thing to verify is the quickstart page at https://moondream.ai/c/docs/quickstart, because that is where the project documents how to run the model locally or in the cloud. The second is the license terms on the weights, since the repository's Apache-2.0 covers the code and the README is silent on the model files. The third is whether the pinned requirements.txt resolves cleanly in your environment, with particular attention to pyvips, which pulls in a native library and is the most likely point of failure.

Editorial conclusion

Moondream fits teams that need image captioning, visual question answering or object detection on hardware where a larger VLM will not fit, and who are willing to follow the quickstart on moondream.ai rather than the GitHub README. It is the wrong choice if you need the repository itself to document installation, if you require a maintained release history, or if your task is plain bounding-box detection where a dedicated detector is cheaper. Before committing, verify two things: whether the pip path in the quickstart installs the same code as the repository, and whether the 0.5B distillation target meets your accuracy bar, since the README describes it as optimized for edge deployment rather than as an equivalent to the 2B model.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. m87-labs/moondream on GitHub
4. Project website
5. README